Paperless-ngx Server: Choose the Hardware, Size It, and Keep It Running
← All posts
GuideNov 20, 2026· 10 min read

Paperless-ngx Server: Choose the Hardware, Size It, and Keep It Running

A Paperless-ngx server is a small Linux machine running four or so Docker containers: the Paperless web app with its background workers, a Redis-compatible broker, a database, and optionally Tika and Gotenberg for Office files. It sits almost idle most of the day. The real load arrives when documents are consumed, because that is when OCR runs, and OCR is CPU-bound. So the practical sizing question is not “how many users” but “how many pages do we scan at once, and how long can we wait for them to become searchable.” A Raspberry Pi 4 or 5, a used mini PC, a NAS, or a small VPS can all work. They differ in how fast intake runs, how safe the files are, and how much you will have to maintain.

This guide covers choosing and running the server itself. For step-by-step installs, see the Paperless-ngx Docker archive tutorial for a Linux VM or the Synology guide for a NAS. Everything below was checked against the official documentation for v3.5.1, the release current at the time of writing.

What actually runs on a Paperless-ngx server

The official Docker Compose templates define the stack. The PostgreSQL variant has three services:

  • webserver: the Paperless-ngx image. Despite the name it does more than serve pages. It also runs the consumer that watches the consume folder and the task workers that do OCR, thumbnails, indexing, matching, and mail fetching.
  • broker: a Redis-compatible message queue. The bundled files now use Valkey, and the FAQ says Redis or other wire-compatible brokers work too.
  • db: PostgreSQL. The SQLite template drops this container and keeps the database as a file in the data volume.

The -tika variants add two more containers, Apache Tika and Gotenberg, so Paperless can ingest .docx, .xlsx, .odt, and email. They add memory and disk overhead, so only enable them if people will actually upload Office documents.

Data lives in four places: data (search index, classifier, SQLite file if used), media (originals, archive PDFs, thumbnails), the database volume, and two bind-mounted folders, consume for intake and export for backups. Where those folders physically sit matters more than which CPU you buy, and we will come back to it.

Where the load comes from

Three jobs use most of the resources:

  1. OCR at intake. Each scanned page goes through OCRmyPDF and Tesseract, and Paperless processes several pages of a document in parallel, one thread per page, up to the limit you set. That keeps every assigned core busy until the file is done, and on a Raspberry Pi it is the step the FAQ calls very slow. The Paperless-ngx OCR settings guide explains how the OCR modes change this.
  2. Classifier training. The automatic matching model retrains on a schedule. The docs note it “takes quite a bit of time” on weak hardware, but it skips the work when nothing has changed.
  3. Web workers. Each webserver worker loads the whole application into memory. The default is one, which is enough for a household or a small office.

Searching, browsing, and editing metadata are light. The FAQ makes the same point about the Raspberry Pi: the interface stays responsive because most of the work happens in the browser, while OCR is the slow part.

That gives you the planning rule. Size CPU for your worst intake batch, size RAM so the containers plus OCR never push the machine into swap, and size disk for years of documents plus backups.

Choosing the Paperless-ngx server host

Host Fits Watch out for
Raspberry Pi 4 or 5 (arm64) One person or a family, light daily scanning Slow OCR on big batches; SD cards are a poor home for the database, so boot or store data on an SSD
Used mini PC or old desktop (x86) Small office, regular scanning, bulk back-scanning projects Power draw and noise if you reuse an old tower; single disk unless you add one
NAS (Synology, QNAP, Unraid) You already back up the NAS and want files on its RAID Low-power NAS CPUs make OCR slow and can make the whole NAS sluggish during intake
VM on an existing hypervisor Offices that already run Proxmox, Hyper-V, or VMware Give it dedicated cores during intake; snapshot is not a backup
VPS or cloud VM Remote teams, no hardware on site Sensitive documents leave your premises; you must handle TLS, updates, and hardening yourself

Two notes from the docs shape this choice. Images are published for arm64, and the FAQ says 32-bit ARMv7 boards “may still function” but recommends moving to arm64. And the setup page lists hosted providers maintained by the community, flagged with a warning to check details carefully. If nobody in the office wants to own a server, that route is worth pricing before you buy hardware.

The documentation does not publish a minimum RAM or CPU figure, and we will not invent one. The reliable way to size is to install on the candidate machine, feed it a realistic batch, and watch docker stats and the time from drop to searchable. If that time is acceptable for your worst week, the machine is big enough.

Storage: plan for originals, archives, and backups

Paperless keeps the original file you uploaded. With the default PAPERLESS_ARCHIVE_FILE_GENERATION=auto, it also writes a PDF/A archive copy for scanned images and image-only PDFs, but skips born-digital PDFs that already contain text. Mostly scanned collections therefore take noticeably more space than the scans alone. Setting the option to never saves disk, at the cost of the browser showing the original instead of the OCR’d archive.

Some practical choices:

  • Put media and the database on an SSD or on RAID storage you already monitor. Avoid SD cards for anything that writes often.
  • If the consume folder sits on an SMB or NFS share, set PAPERLESS_CONSUMER_POLLING_INTERVAL to a positive number of seconds. The default relies on filesystem notifications, which the docs say may not work reliably on network filesystems.
  • Scanners that write slowly over the network can trigger consumption of half-written files. Raise PAPERLESS_CONSUMER_STABILITY_DELAY (default 5 seconds) if you see truncated PDFs.
  • Leave room for the export folder. A full export includes every document and thumbnail, so it can approach the size of media.

SQLite or PostgreSQL

SQLite is the default and has the fewest moving parts. The low-power guidance recommends it to save resources, and points to troubleshooting notes for SQLite locking errors. PostgreSQL is what the setup docs recommend for new installs, and the configuration page describes it as the choice for multi-user or higher-throughput setups. MariaDB is supported, with documented caveats.

A reasonable rule: a single-user Pi can stay on SQLite. Anything shared by an office, or anything that will hold tens of thousands of documents, should start on PostgreSQL, because moving later means an export and import.

Tune workers to the cores you have

Two settings control parallel work:

  • PAPERLESS_TASK_WORKERS sets how many background tasks run at once. In v3.5.1 it defaults to 1.
  • PAPERLESS_THREADS_PER_WORKER sets how many pages of one document are OCR’d in parallel. If unset, Paperless divides the CPU count by the number of workers.

The configuration docs warn that workers multiplied by threads must not exceed your core count, or Paperless becomes “extremely slow.” On a four-core machine that also runs other services, two workers with one thread each leaves headroom, and that is the example the setup page gives for the Raspberry Pi. If you mostly scan long single documents, one worker with four threads finishes each file faster. If you scan many short receipts, more workers with fewer threads clears the queue sooner.

On slow hardware, also look at PAPERLESS_WORKER_TIMEOUT. The default is 1800 seconds, and the docs say weak machines may not finish OCR on large documents within it. A timeout shows up as a failed task, not a slow one, so check the task list after your first big batch.

Take load off the box

The setup page has a short section on less powerful devices. The settings that make the biggest difference:

# docker-compose.env
PAPERLESS_OCR_MODE=auto          # keep the default, reuse existing text
PAPERLESS_OCR_PAGES=1            # OCR only page one
PAPERLESS_OCR_CLEAN=none         # faster, slightly worse OCR
PAPERLESS_WEBSERVER_WORKERS=1    # less RAM
PAPERLESS_TASK_WORKERS=2
PAPERLESS_THREADS_PER_WORKER=1

PAPERLESS_OCR_PAGES=1 is a real trade: text on later pages will not be searchable. It is fine for invoices and letters, and a poor choice for contracts where the clause you need is on page nine.

The other lever is to do OCR somewhere else. Many scanners can produce searchable PDFs, and with OCR mode auto Paperless reuses that text instead of running Tesseract again. Paperless also has a built-in remote OCR option, which in v3.5.1 supports only Azure AI. For metadata rather than the text layer, a workflow webhook can send new documents to an external service. That is how ocrskill.com fits: Paperless keeps local OCR for search, and ocrskill.com reads the page with a vision model and returns the document type, issue date, correspondent, and a review flag, which Paperless writes back. The setup is in the archive tutorial linked above. Any external service means document content leaves the server, so decide which document types are allowed to go out before you enable it.

Network access and security

For the first week, keep Paperless on the LAN only, at the server’s IP and the mapped port. Before anyone reaches it from outside:

  • Set a long random PAPERLESS_SECRET_KEY. It is required, and Paperless will not start without it.
  • Put it behind a reverse proxy with HTTPS, and set PAPERLESS_URL to the public origin without a trailing slash. Most “page loads but login fails” problems come from a missing or wrong PAPERLESS_URL.
  • Consider a VPN or a private overlay network instead of opening a port. A document archive holds tax records, IDs, and contracts.
  • Create a normal user for daily work. The setup docs point out that superusers have full access to every object.

The project wiki has user-maintained pages on reverse proxies and security tools like Fail2ban.

Backups and updates

The administration docs describe two backup approaches for Docker installs: copy the volumes, or run the document exporter. The exporter is easier to reason about:

docker compose exec -T webserver document_exporter ../export -z

-T avoids TTY errors when run from cron. The exporter updates an existing export incrementally, so pairing it with rsync to another machine works well. Three caveats from the docs: an export can only be imported into the same Paperless version, API tokens are not included, and you should run it when nothing is being consumed. Copy the export off the server, and test a restore into a throwaway instance now and then.

Updates follow the same pattern every time. Stop consumption, back up, then:

docker compose down
docker compose pull
docker compose up -d

up applies database migrations. Read the release notes before major version jumps; the v3.0 upgrade, for example, had migration steps that needed manual work.

Limitations of self-hosting

A self-hosted server is yours to patch, back up, and replace when the disk dies. If the only copy of your documents is on that box, a failed drive is a lost archive. Small offices without anyone comfortable with Docker should either budget for a contractor to maintain it or look at managed hosting. Slow hardware also shapes behavior: if a scan takes ten minutes to become searchable, people go back to the filing cabinet.

Conclusion

Pick the server by testing your heaviest intake batch on it, not by reading spec sheets. Before you call it done, confirm five things: the machine finishes your worst batch in an acceptable time without hitting the worker timeout, workers times threads stays within the core count, media and the database sit on storage that is monitored and not an SD card, an export runs on a schedule and lands on a different machine, and remote access goes through HTTPS with a correct PAPERLESS_URL. Once those hold, the server mostly stays out of your way, and the remaining work is classification, which you can automate with workflows or an external service.