Published

Paperless-ngx

Document management system: scanned papers, PDFs and photos are OCRed, archived as searchable PDF/A, and sorted by tags, correspondents and document types learned from your own filing. Fits households and small offices that want a paperless archive on their own server. The stack is the Paperless container, PostgreSQL and a Valkey broker, plus Tika and Gotenberg for Office files and e-mails.

Resources by load level

What the app itself needs at each level, next to what we recommend for a server that runs only this app.

Level	What it means	App requirements	Recommended
LightEstimate	Household or 1-3 users: ~100 documents/month (~500 pages), an archive of up to 1,000 documents, one document OCRed at a time.	2.25 vCPU · 2.75 GiB RAM · 29.75 GiB disk	2.82 vCPU · 4.8 GiB RAM · 43.988 GiB disk
MediumEstimate	Small office, up to 10 users: ~500 documents/month (~2,500 pages), an archive of up to 5,000 documents, mail rules fetching invoices.	3.25 vCPU · 3.25 GiB RAM · 110.25 GiB disk	4.02 vCPU · 5.4 GiB RAM · 136.563 GiB disk
HeavyEstimate	Office of up to 25 users: ~2,500 documents/month (~12,500 pages), an archive of up to 20,000 documents, daily scanner batches.	5.25 vCPU · 4.25 GiB RAM · 411.25 GiB disk	6.42 vCPU · 6.6 GiB RAM · 482.713 GiB disk

Recommended = app requirements + system baseline + safety headroom, under sizing policy 2026.10.0. Options stay at their defaults. “Estimate” means the sources give no number for that case, so it is worked out from them by the method stated under Components. How the numbers are built

Size it in the Stack Sizer

Ready-to-run files

Support level Supported

Compose template from the official sources; not yet verified by a run.

Create docker-compose

Components

What each component needs at each load level, before baseline and headroom.

vCPU / GiB RAM / GiB disk
Component	Light	Medium	Heavy	Sources
Paperless-ngx (web server, task worker, consumer) (app)	1 / 1.5 / 23	2 / 2 / 103.5	4 / 3 / 404.5	[10][11][19][21][23]
PostgreSQL (database)	1 / 1 / 6.5	1 / 1 / 6.5	1 / 1 / 6.5	[36][37][38][39][40][41][42]
Valkey (Celery task broker) (queue)	0.25 / 0.25 / 0.25	0.25 / 0.25 / 0.25	0.25 / 0.25 / 0.25	[11][19][23][26]
Gotenberg (Office and e-mail to PDF) (other)	—	—	—
Apache Tika (Office text extraction) (other)	—	—	—

How the estimates are worked out

Paperless-ngx (web server, task worker, consumer) · Light: No upstream sizing. RAM: a v3 install was reported at ~650 MB idle and ~1,100 MB during OCR (one task worker, the default); 1,100 MB (1.02 GiB) plus ~0.5 GiB for large scans (ImageMagick has no memory limit by default). vCPU: OCR pages run in threads up to the core count; ~5 documents a working day need one core. Disk: 2.4 GiB unpacked image (2.5) + 0.5 GiB data (index, classifier, logs) + 10 GiB media (10 MB per document, the top of the reported 5-10 GB per 1,000) + 10 GiB for one full document_exporter copy.
Paperless-ngx (web server, task worker, consumer) · Medium: RAM: the reported ~1,100 MB during OCR plus ~0.4 GiB for a second OCR page thread (THREADS_PER_WORKER follows the core count) and more UI sessions, rounded up to 2 GiB (ANAROQ estimate). vCPU: 2, so a scanned batch of ~25 documents a day does not block search and the UI. Disk: 2.5 GiB image + 1 GiB data + 50 GiB media (5,000 × 10 MB) + 50 GiB for the exporter copy.
Paperless-ngx (web server, task worker, consumer) · Heavy: RAM: the reported ~1,100 MB during OCR plus ~0.4 GiB for each of three more OCR page threads on 4 cores, rounded up to 3 GiB (ANAROQ estimate). vCPU: 4 page threads, so ~115 documents a working day are OCRed within the default 1,800 s task limit even in batches. Disk: 2.5 GiB image + 2 GiB data + 200 GiB media (20,000 × 10 MB) + 200 GiB for the exporter copy.
PostgreSQL · Light: Embedded metadata DB with the image's default config: equals the PostgreSQL profile's light preset (≤ 5 GB data, ≤ 20 concurrent connections) at every load level. Light preset method: shared_buffers 25% of RAM, worst-case work_mem/maintenance_work_mem budget, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
PostgreSQL · Medium: Embedded metadata DB with the image's default config: equals the PostgreSQL profile's light preset (≤ 5 GB data, ≤ 20 concurrent connections) at every load level. Light preset method: shared_buffers 25% of RAM, worst-case work_mem/maintenance_work_mem budget, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
PostgreSQL · Heavy: Embedded metadata DB with the image's default config: equals the PostgreSQL profile's light preset (≤ 5 GB data, ≤ 20 concurrent connections) at every load level. Light preset method: shared_buffers 25% of RAM, worst-case work_mem/maintenance_work_mem budget, 0.5 GiB image + 5 GiB data + 1 GiB WAL.
Valkey (Celery task broker) · Light: Valkey only carries Celery task messages and results, which expire after an hour (CELERY_RESULT_EXPIRES 3600); a v3 install reported ~10 MB. 0.25 vCPU / 0.25 GiB is the smallest share used in the catalog. Disk: 45.9 MB unpacked image + a small RDB snapshot, rounded up to 0.25 GiB.
Valkey (Celery task broker) · Medium: As light: task messages and hour-long results only; a few hundred tasks a day stay far below the 0.25 GiB share.
Valkey (Celery task broker) · Heavy: As light: one task worker drains the queue one document at a time, so the queue stays small even with ~2,500 documents a month.
office-documents · Apache Tika (Office text extraction): No upstream sizing. A v3 install reported Tika at ~160 MB idle and ~400 MB while parsing; 0.75 GiB leaves room for the JVM heap to grow on larger files. vCPU: one parse at a time (one task worker), half a core. Disk: 401 MB unpacked image, rounded up to 0.5 GiB; Tika keeps no data.
office-documents · Gotenberg (Office and e-mail to PDF): Gotenberg's docs ask for at least 1Gi of memory for a smooth experience (their demo runs on 512 MB / 0.5 CPU, rate-limited), and LibreOffice conversion is resource-heavy; 1 vCPU / 1 GiB (GB taken as GiB). Disk: 1,710,739,968 B unpacked image (1.59 GiB), rounded up to 1.75 GiB; conversions use /tmp only.

Options that change resources

office-documents

Office documents and e-mails: adds Apache Tika (text extraction) and Gotenberg (conversion to PDF), as in the official -tika Compose file, so .docx, .xlsx, .pptx, .odt and .eml files can be consumed. Without it, Paperless takes PDFs, images and plain text only.

Default: off

When on: Apache Tika (Office text extraction) +0.5 vCPU · +0.75 GiB RAM · +0.5 GiB disk [11][23][33]
When on: Gotenberg (Office and e-mail to PDF) +1 vCPU · +1 GiB RAM · +1.75 GiB disk [23][27][28][30]

Ports

Public ports are meant to be reached from outside the stack, usually through a reverse proxy; internal ones stay on the stack's own network.

Component	Port	Exposure	Purpose	Sources
Paperless-ngx (web server, task worker, consumer)	8000/tcp	Public, through a proxy	Web UI, REST API and WebSocket status updates (HTTP; put behind TLS)	[5][16]
PostgreSQL	5432/tcp	Internal only	PostgreSQL connections from Paperless	[2][11]
Valkey (Celery task broker)	6379/tcp	Internal only	Celery task broker and result backend (Redis protocol)	[11][24]
Gotenberg (Office and e-mail to PDF)	3000/tcp	Internal only	Gotenberg conversion API used by Paperless (office-documents option)	[3][27]
Apache Tika (Office text extraction)	9998/tcp	Internal only	Tika Server parsing API used by Paperless (office-documents option)	[3][31]

Every port in the catalog, with conflicts between apps

User and permissions (UID/GID)

The user each container's process runs as, and the paths it writes to. A bind mount for one of these paths must be writable by that UID:GID.

Component	UID:GID	User	Starts as root	Writes to	Sources
Paperless-ngx (web server, task worker, consumer)	1000:1000	`paperless`	Yes, prepares its directories, then drops to this user	`/usr/src/paperless/data/usr/src/paperless/media/usr/src/paperless/export/usr/src/paperless/consume`	[5][6][16][18]
PostgreSQL	999:999	`postgres`	Yes, prepares its directories, then drops to this user	`/var/lib/postgresql/var/run/postgresql`	[34][35][41]
Valkey (Celery task broker)	999:1000	`valkey`	Yes, prepares its directories, then drops to this user	`/data`	[24][25]
Gotenberg (Office and e-mail to PDF)	1001:1001	`gotenberg`	No	—	[27][29]
Apache Tika (Office text extraction)	35002:35002	—	No	—	[32][33]

Storage growth

How much each component's data grows per month at each load level, on top of the disk in the profile. A value marked Assumption is ANAROQ's stated assumption, not a figure from the sources; the notes say what it rests on.

GiB per month
Component	Light	Medium	Heavy	Sources
Paperless-ngx (web server, task worker, consumer)Derived	2	9.5	47	[12][23]
PostgreSQLAssumption	0.01	0.05	0.25

What the growth figures rest on

Paperless-ngx (web server, task worker, consumer): Documents/month × 10 MB (original, archived PDF/A and thumbnail; top of the reported 5-10 GB per 1,000 documents), doubled for the exporter copy in the export volume: 100 → 1.9, 500 → 9.3, 2,500 → 46.6 GiB, rounded up. Nothing expires: deleted documents leave the trash after 30 days.
PostgreSQL: The database holds metadata and each document's extracted text (files stay in the media volume): an assumed ~20 KB per document plus audit log rows, 100/500/2,500 documents a month. Paperless publishes no growth figure.

Upgrade and rollback

How to move to a new version safely, and how to go back if it fails.

Back up first

Run document_exporter into the export volume, and also copy the PostgreSQL, data and media volumes (or pg_dump plus the two volumes): an export can only be imported into the same Paperless version. [12]

Upgrade steps

Read the release notes of every version you skip; to reach v3 you must first be on 2.20.15 and follow the v3 migration guide. [12][13]
Wait until no document is being consumed, take the backup, then docker compose down. [12]
Set the new pinned image tag, run docker compose pull, then docker compose up -d; database migrations run when the container starts. [12]DerivedThe docs upgrade with pull and up on the latest tag (or a pinned series); with a pinned version the tag is changed first.

Roll back

Stop the stack, restore the PostgreSQL, data and media volumes taken before the upgrade, set the old tag back and start. Migrations are not reversed automatically, and the pre-upgrade export imports only into the old version. [12]DerivedThe docs give no rollback procedure; this follows from their volume backups and the rule that an export needs the same version.

Known breaking changes

In 3.0.0: PAPERLESS_SECRET_KEY is required (no built-in default), and PostgreSQL users must set PAPERLESS_DBENGINE=postgresql; the separate DB SSL, timeout and pool variables moved into PAPERLESS_DB_OPTIONS. [13]
In 3.0.0: OCR and archive settings were split: OCR_MODE skip and skip_noarchive and OCR_SKIP_ARCHIVE_FILE are removed (now OCR_MODE=auto and ARCHIVE_FILE_GENERATION), duplicates are no longer rejected by default, and document encryption is gone (decrypt before upgrading). [13][15]
In 3.0.0: Search moved from Whoosh to Tantivy and the index is rebuilt on the first start; note and custom-field searches use notes.note: and custom_fields.value:. Task history is cleared, consume scripts get environment variables only, and behind a proxy login may need the trusted-proxy settings to avoid 403. [13]
In 3.0.0: x86-64 CPUs without SSE4.2 (x86-64-v2) crash the worker when the classifier loads; on such hardware set PAPERLESS_TRAIN_TASK_CRON=disable. [13]
In 2.18.0: PostgreSQL 14 is the minimum supported version. [12]

Limits

One task worker by default (PAPERLESS_TASK_WORKERS=1): documents are consumed one at a time, and only the pages of one document run in parallel (one thread per core). More workers need more RAM, and workers × threads must not exceed the cores. [11][19]
Without the office-documents option only PDFs, images and plain text are consumed; Word, Excel, PowerPoint, LibreOffice files and .eml e-mails need Tika and Gotenberg. [11][14]
The image OCRs English, German, French, Italian and Spanish only. Hebrew needs the ocr-hebrew option, which installs the language at start (internet required, not possible in rootless mode). [7][10][11]
Since v3, x86-64 CPUs need SSE4.2 (x86-64-v2): on older or low-power CPUs the classifier crashes the worker unless PAPERLESS_TRAIN_TASK_CRON=disable. [13]

Security

Serve Paperless over HTTPS from a reverse proxy and set PAPERLESS_URL to the public address, which limits the allowed hosts and CSRF origins. Never use PAPERLESS_AUTO_LOGIN_USERNAME on an exposed instance. [11]
Without PAPERLESS_ADMIN_USER the first visitor is asked to create the superuser, and a superuser sees every document. The template creates it from .env at the first start; use a normal account for daily work. [10][11]
Task messages on the broker are signed with PAPERLESS_SECRET_KEY, and Valkey has no password, so keep it on the internal network only. Gotenberg runs with JavaScript off and may load only local /tmp files, so e-mails can't fetch tracking pixels or scripts. [3][11][19]

Backup

Run docker compose exec -T paperless-ngx document_exporter ../export on a schedule: it writes documents, thumbnails and a manifest of the whole database to the export volume and updates it incrementally. Copy that volume off the server. API tokens are not included, and an export imports only into the same version. [12]
For a full restore of the same version, back up the media volume (the documents), the data volume (index, classifier, settings) and PostgreSQL (pg_dump), with no document being consumed at that time. [12][14]