A document management system that watches a folder, OCRs whatever lands in it, and files it by correspondent, type and tag. It replaces the shoebox of receipts and the vendor cloud portals you keep re-downloading statements from.
Our verdict on Paperless-ngx#
Paperless-ngx is the reason people finally throw paper away, and it is also the most container-heavy thing in this category. A normal install is five services: the app on port 8000, Valkey as the broker, Postgres, plus Gotenberg and Tika if you want Office files consumed. Version 3.0 in July 2026 was a genuine break. It swapped the Whoosh search index for tantivy, removed document and thumbnail encryption outright, deleted the positional arguments from pre and post consume scripts, and dropped API versions below 9. Read those notes before you pull. The real cost is CPU and RAM at consume time, not at rest: OCR on a long scan will chew several hundred megabytes per worker thread, so on a 2 GB Pi you set PAPERLESS_TASK_WORKERS=1 and PAPERLESS_THREADS_PER_WORKER=1 and let a bulk import run overnight. Everything after that is quiet.
Who Paperless-ngx is for#
Choose it if
- Anyone with a document feed scanner and a filing cabinet they want to empty, who will accept a nightly OCR queue
- Households tracking warranties, tax paperwork and insurance where full text search across ten years of PDFs is the whole point
- Small businesses that need mail-in invoices consumed automatically from an IMAP mailbox
- Operators comfortable running Postgres and reading release notes before a major version bump
Look elsewhere if
- Your only hardware is a 1 GB single-board computer; OCR will thrash and consumption will time out
- You want a wiki or a notes app; Paperless indexes finished documents, it does not let you write them
- You cannot commit to running
document_exporteron a schedule, because a raw copy of the media volume will not restore your filing
What running it actually looks like#
Copy one of the project's compose files, docker-compose.env and .env into a directory and bring it up. Two host directories get bind mounted, ./consume and ./export, while data and media are named Docker volumes. Set PAPERLESS_OCR_LANGUAGE, PAPERLESS_TIME_ZONE and USERMAP_UID/USERMAP_GID to match whoever writes into the consume folder, or the scanner drops files the container cannot read. First boot runs migrations and builds the search index through the s6 init chain, which takes a minute; create the first user with PAPERLESS_ADMIN_USER and PAPERLESS_ADMIN_PASSWORD or with document_createsuperuser. Upgrades are a pull and a restart, and migrations run automatically. Major versions are where it bites: 3.0 changed the search backend and removed features, so pin a tag rather than tracking latest.
Resource profile#
- Memory
- 450 MB idle, around 1200 MB in ordinary use. Estimate for the full five container stack at rest; the app itself is modest and Postgres plus Valkey account for roughly a third. OCR is what moves the number.
- CPU and acceleration
- Flat until something enters the consume folder, then OCRmyPDF, Ghostscript and Tesseract saturate every core you gave them. `PAPERLESS_TASK_WORKERS` times `PAPERLESS_THREADS_PER_WORKER` must not exceed your core count or consumption gets slower, not faster. No GPU use.
- Storage growth
- Two copies of every document by default: the original plus a generated PDF/A archive file, so budget roughly double your scan volume. Set `PAPERLESS_ARCHIVE_FILE_GENERATION=never` to halve it at the cost of in-browser viewing.
- Operational load
- 3 of 5, Moderate. Five containers, a real database, and an upgrade path where major versions change the search backend and remove features. Restore is a documented import, not a file copy, and it must be done with a matching version.
Figures describe a small single-household install and are the working assumptions behind our stack planner. Your numbers will differ with library size, user count and hardware. See methodology.
Data and backup surface#
Back up with document_exporter, not by copying the media tree. docker compose exec -T webserver document_exporter ../export writes originals, archive PDFs, thumbnails and a manifest.json containing every tag, correspondent, custom field and permission. Media on its own is a pile of files named 0000123.pdf with no metadata; the database is where your filing system actually lives. Rerunning the exporter updates in place, so you can rsync the export directory for incremental backups. -d prunes deleted documents, -na -nt skips archive files and thumbnails, which you can regenerate later with document_archiver and document_thumbnails. The search index under data/ and classification_model.pickle are regenerable and can be excluded.
Derived backup shape
Postgres dump. pg_dump (or pg_dumpall) into a file, then snapshot that file plus the app's data volume.
Traps and surprises#
An export only restores into the same version
The docs are explicit: you cannot import an export made by one Paperless version into a different one, because the manifest is an exact image of the database and migrations change the layout. Store the image tag next to every export. If you find yourself restoring an old export, spin up that exact tag first, import, then upgrade forward through the normal migration path.
OCR language packs install on every container start
The image ships English, German, Italian, Spanish and French. Anything else goes in PAPERLESS_OCR_LANGUAGES as space-separated Debian package suffixes (chi-tra, not chi_tra), and the container apt-installs them at boot, so startup needs working outbound network every time. The docs warn this option must not be used in rootless containers, where it simply fails.
The consume folder does not work on NFS or SMB by default
Paperless watches the consume directory with inotify, which network filesystems do not deliver. Files land and nothing happens, with no error. Set PAPERLESS_CONSUMER_POLLING_INTERVAL to a positive number of seconds to switch to polling. This is the single most common 'my scanner is not working' report.
3.0 removed document encryption and changed consume scripts
Version 3.0 (July 2026) dropped support for document and thumbnail encryption entirely, so an instance using the old passphrase feature must be decrypted before upgrading. It also removed the positional arguments passed to pre and post consume scripts, so any custom hook that read $1, $2 and friends silently stops working and must be rewritten against the environment variables.
Tika and Gotenberg are optional and easy to forget
Without the tika and gotenberg containers plus PAPERLESS_TIKA_ENABLED=1, Word, Excel and PowerPoint files are rejected at consume time rather than converted. Adding them later means editing compose and restarting, which is fine, but the two extra containers are roughly another 400 MB of resident memory that people do not budget for on small boxes.
Specifications#
- Category
- Documents, notes and knowledge
- Licence
- GPL-3.0 (Copyleft)
- Written in
- Python / Django, Angular frontend
- First release
- 2022
- Maturity
- Mature
- Datastore
- PostgreSQL (SQLite and MariaDB also supported)
- Default ports
8000- Ships as
- docker compose, bare metal install, unraid/synology community templates
- arm64 builds
- Yes
- Identity
- Native OIDC. OIDC through django-allauth, configured as a JSON blob in `PAPERLESS_SOCIALACCOUNT_PROVIDERS` plus an entry in `PAPERLESS_APPS`; group sync from claims works, and a `Remote-User` header mode exists separately.
- Replaces
- Evernote (document scanning), Dropbox Scan, Adobe Acrobat, DEVONthink
- Project site
- docs.paperless-ngx.com
- Source
- github.com/paperless-ngx/paperless-ngx
- Documentation
- github.com/paperless-ngx/paperless-ngx/blob/main/docs/setup.md
Alternatives to Paperless-ngx#
Everything else in documents, notes and knowledge, closest in operational weight first.
| Tool | Ops load | Idle RAM | Licence |
|---|---|---|---|
| Docmost | 3, Moderate | 500 MB | AGPL-3.0 core, proprietary Docmost Enterprise licence for `ee` directories |
| Wiki.js | 3, Moderate | 260 MB | AGPL-3.0 |
| BookStack | 2, Light | 260 MB | MIT |
| HedgeDoc | 2, Light | 250 MB | AGPL-3.0 |
| Outline | 4, Heavy | 550 MB | BUSL-1.1 (Change Date 2030-09-01, converts to Apache-2.0) |
| Trilium Notes | 2, Light | 200 MB | AGPL-3.0 |
Where Paperless-ngx comes up elsewhere#
Migration guides
Guides
Research
Sources#
Facts on this page were checked against the project's own material. Where a number is our own estimate rather than a published figure, the text says so.
Published . Last reviewed . Found something out of date? Tell us and we will fix it and log the change.