Paperless-ngx

What Paperless-ngx Does and Why It Exists

Paperless-ngx is a self-hosted document management system designed to turn a pile of scanned paper—or digital files—into a searchable online archive. The project describes itself as transforming "your physical documents into a searchable online archive so you can keep, well, less paper." It is the official successor to the original Paperless and Paperless-ng projects, explicitly structured to distribute maintenance responsibility across a contributor team rather than a single author.

The system has two runtime components: a consumer that watches a directory and ingests every file dropped into it, and a web server that provides the browser interface for search, tagging, and editing. Documents placed in the consume folder are processed automatically—OCR runs, text is extracted, and the file is stored in PDF/A format alongside the unaltered original. All data stays on the operator's own server; nothing is transmitted externally unless the operator explicitly configures it.

Key Capabilities

Paperless-ngx performs full-text OCR via the Tesseract engine, which supports more than 100 languages. Scanned images with no embedded text become searchable after ingestion. The system can also process Office documents (Word, Excel, PowerPoint, and LibreOffice equivalents) when Apache Tika is included in the deployment stack.

Organization uses four metadata axes: tags, correspondents, document types, and custom fields. Tags work like labels rather than folders—a single document can carry multiple tags simultaneously, and multiple documents can share a tag. Machine learning is used to automatically suggest or assign tags, correspondents, and document types based on document content.

The web interface includes full-text search with auto-completion, relevance ranking, query-term highlighting, and a "more like this" feature for finding related documents. Saved views can be pinned to the dashboard or sidebar. Documents can be shared via public links with an optional expiration date. The system also supports multiple file versions under a single metadata entry.

Optional AI features—LLM-based document suggestions, chat-with-your-documents, and similar-document retrieval—are available but disabled by default and must be explicitly enabled.

Installing with Docker Compose

Docker is the recommended deployment method. The project provides an interactive script that automates the full setup:

The script asks configuration questions, creates the required files, pulls the image, starts the containers, and creates the initial superuser account. After it finishes, the web interface is accessible at http://127.0.0.1:8000 by default.

For manual control, the repository's /docker/compose directory contains several docker-compose.*.yml templates. For new installations, the documentation recommends PostgreSQL as the database backend. The compose stack includes the webserver, a PostgreSQL or SQLite database, a Redis broker for task queuing, and optionally Gotenberg and Apache Tika for document conversion and text extraction from Office files.

The Docker Compose files note that paperless "listens on port 8000" by default and "supports amd64, arm and arm64 hardware." To change the listening port, edit the ports mapping in the compose file:

Configuration is managed through a docker-compose.env file when running via Docker. Docker secrets are supported: append _FILE to a configuration key and point it at a secrets file—for example, PAPERLESS_DBUSER_FILE=/var/run/secrets/password.txt.

To run the container as a rootless user, set user: in the compose file to the host UID and GID:

Note that rootless mode is incompatible with PAPERLESS_OCR_LANGUAGES—additional language packs cannot be installed in a rootless container.

Bare-Metal Prerequisites and Limitations

The bare-metal route is available for advanced users who need direct control over all components. The documentation states that "Paperless runs on Linux only, Windows is not supported." Python 3.11, 3.12, 3.13, or 3.14 is required; the project policy is to support at least the three most recent Python versions and drop versions as they reach end-of-life.

OCR depends on Tesseract >= 4.0.0 and OCRmyPDF, which itself requires Ghostscript, unpaper, qpdf, and related libraries. The bare-metal dependency list is considerably longer than the Docker path, making Docker the practical choice for most deployments.

On NFS or other file systems that lack inotify support, the consumer's default file-watch mechanism will not detect new documents. Setting PAPERLESS_CONSUMER_POLLING_INTERVAL to a positive integer switches the consumer to polling mode.

Sources

• GitHub repository: https://github.com/paperless-ngx/paperless-ngx
• Project README: https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/README.md
• Official setup documentation: https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docs/setup.md
• Documentation index (features list): https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docs/index.md
• Basic usage documentation: https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docs/usage.md
• License (GPL-3.0): https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/LICENSE
• Docker Compose template (PostgreSQL): https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/docker/compose/docker-compose.postgres.yml