Paperless-ngx: scan, OCR and find every document you own

Paperless-ngx turns a shoebox of paper and a downloads folder full of badly named PDFs into one searchable archive. Drop in a scan, and it reads every word with OCR, guesses the date, sender and type, and files it so a search for one word inside the document finds it years later.

Published Nov 17, 2026 · Last updated Nov 18, 2026

Everyone has the same filing problem: the insurance letter is called scan_0042.pdf, the warranty is a photo on a phone, and the tax document is an email attachment you will never find again under pressure. Paperless-ngx fixes the retrieval problem rather than demanding perfect filing discipline from you. You feed it documents through one folder; it does the reading, indexing and suggesting. Your job shrinks to confirming its guesses for a few seconds per document — and after a while, its machine-learning classifier learns from those confirmations and gets most new documents right on its own.

How the consume pipeline works

Paperless watches a folder called consume. Anything that lands there — a scan from a scanner’s network folder, a PDF you drag in, a file a sync app drops from your phone — is picked up, processed and then removed from consume, because the document now lives inside Paperless’s own managed storage. Processing means: extract or create the text layer with Tesseract OCR (via OCRmyPDF, which also produces a clean archival PDF), detect the date on the page, and run the classifier to suggest a correspondent (who sent it), a document type (invoice, statement, letter) and tags. Optional helper containers, Apache Tika and Gotenberg, let it also ingest Office documents and email files by converting them to PDF first. The result appears in your inbox view, ready for a quick confirm-and-save.

Pipeline diagram from scanner and downloads through the consume folder to OCR, classification and searchable archive
The consume pipeline: however a document arrives, it passes through OCR and classification once, then becomes fully searchable.

What you need

Step-by-step installation

  1. Create the folders: a project folder containing consume and export folders, plus persistent volumes (or folders) for data, media and the Postgres database. Note who owns these folders — the container user needs to read and delete files in consume, which is what the USERMAP_UID and USERMAP_GID settings are for.
  2. Write the compose file using the example below, based on the project’s official Postgres template. Set a random PAPERLESS_SECRET_KEY and a strong database password — do not ship the placeholder values.
  3. Set your language and time zone before the first start: PAPERLESS_OCR_LANGUAGE=eng for English, or combine codes with a plus sign such as eng+deu for English and German. If your language is not one of the five bundled, add it with PAPERLESS_OCR_LANGUAGES so it is installed on first start. Every extra language slows OCR on every page, so list only languages you actually receive documents in.
  4. Start the stack with docker compose up -d and wait for the webserver logs to show it is listening. First start runs database migrations and can take a few minutes.
  5. Create the administrator account with the management command: docker compose exec webserver python manage.py createsuperuser, then sign in at http://your-nas-address:8000.
  6. Test the pipeline with one harmless document. Drop a simple PDF into consume, watch it disappear, and find it in the inbox with searchable text. Search for a word that appears only inside the document — if that finds it, OCR and indexing both work.
  7. Point your scanner at consume. Configure the scanner or printer to save scans to the consume shared folder, ideally as PDF. If your scanner can only email scans, Paperless can also fetch mail from an IMAP account with mail rules — set that up later, once the folder path works.
  8. Teach the classifier. For the first few dozen documents, correct the suggested correspondent, type and tags before saving. Create a small, consistent set: correspondents are senders (a bank, an insurer, a utility), types are kinds (statement, invoice, policy), and tags are yours alone (tax-2026, house, car). Consistency is what the classifier learns from; twenty near-duplicate tags teach it nothing.
  9. Use subfolders as a shortcut if you like: with the consumer’s recursive and subfolder-as-tag settings enabled, dropping a file into consume/invoices/ tags it automatically. This is a good trick for a scanner profile dedicated to one kind of paperwork.
  10. Set up the exporter backup (below) and keep remote access private — use a VPN-style connection or an HTTPS reverse proxy rather than exposing port 8000. This archive will contain your most sensitive documents; treat its login accordingly and enable a strong, unique password.

A concrete Docker Compose example

services:
  broker:
    image: redis:7
    restart: unless-stopped
    volumes:
      - redisdata:/data

  db:
    image: postgres:16
    restart: unless-stopped
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: use-a-long-random-password

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
    ports:
      - "8000:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_SECRET_KEY: replace-with-a-long-random-string
      PAPERLESS_OCR_LANGUAGE: eng
      USERMAP_UID: "1000"
      USERMAP_GID: "1000"

volumes:
  data:
  media:
  pgdata:
  redisdata:

Notice what the volumes say about the design: consume and export are plain folders you interact with, while the archive itself lives in managed volumes. Never reorganise files inside the media volume by hand — Paperless tracks originals, archival versions and thumbnails in its database, and manual tidying breaks those links.

Diagram showing a document record with correspondent, document type, tags and date fields beside a search box
Findability comes from three simple fields — correspondent, type and tags — plus full-text search over the OCR text.

Backups with the document exporter

Paperless ships a purpose-built exporter: docker compose exec webserver document_exporter ../export writes every document, its metadata and the information needed to rebuild the archive into the export folder. The matching importer can rebuild a complete working archive from an export on a fresh install, which makes the exporter both your backup and your migration path — with the version caveat below. Run it interactively as shown; for a scheduled job (cron, a NAS task scheduler, a backup script) use the non-interactive form with -T, which skips allocating a terminal that cron cannot provide and avoids TTY-related errors:

docker compose exec -T webserver document_exporter ../export

Whichever form you run, copy the export folder somewhere else afterwards — another drive, another machine, cloud storage. An export that lives only on the same NAS is not disaster recovery: if the NAS dies, the backup dies with it.

One limitation the project’s own documentation is blunt about: an export is tied to the Paperless version that created it. An export made by one version cannot reliably be imported into a different version — the export holds an exact image of the database, and migrations change its layout — so export and restore using compatible versions. Keep a record of the exact Paperless version that produced each export (the exporter writes it into the export’s metadata), and when restoring, install that same version first, import, and only then upgrade. Exports also leave out API tokens, so after a restore you will need to regenerate tokens for any app or script that connects to Paperless. And test the import from time to time on a throwaway install: an emergency restore is the worst moment to discover a version mismatch. A raw copy of the volumes also works as a backup if the database is included and the stack is stopped or consistent, but the exporter is the method the project itself recommends.

Common mistakes and troubleshooting

Files sit in consume and are never picked up

Check permissions first: if the container user cannot read and delete the file, consumption fails and the logs will say so — align USERMAP_UID/USERMAP_GID with the owner of the consume folder. On some network filesystems, change notifications do not arrive; enabling the consumer’s polling setting (PAPERLESS_CONSUMER_POLLING) makes Paperless check the folder on an interval instead.

OCR text is empty or garbled

Usually the wrong language or a poor scan. Confirm PAPERLESS_OCR_LANGUAGE matches the document’s language and that extra languages were actually installed via PAPERLESS_OCR_LANGUAGES. Scan at 300 dpi, in a well-lit, straight capture; no OCR engine rescues a blurred, skewed photo of a crumpled letter. You can re-run OCR on an existing document from the admin tools after fixing the cause.

The classifier suggests nonsense

It has too little — or too inconsistent — training data. It learns from documents you have confirmed, so early suggestions are guesses. Keep correspondent and type lists tidy, merge duplicates, and give it a few dozen consistent examples before judging it. Matching rules you define manually always take priority over its guesses, so pin the important recurring senders with explicit rules.

Dates are wrong on statements

Paperless looks for a plausible date in the text, and documents full of dates (due dates, period ranges, birthdays) can fool it. Correct the date on save — the classifier improves — and, for stubborn correspondents, set a date order or format hint in settings so day/month order is interpreted the way your country writes it.

Official documentation and references

Frequently asked questions

Does Paperless-ngx replace my folder structure?

Inside the archive, yes, deliberately: Paperless stores files in its own managed layout and finds them by search, correspondent, type and tags instead of by folder path. You can configure filename formatting if you want exported files to follow a pattern, but the mental shift — search, don’t browse — is the point of the tool.

Can it handle documents that arrive by email?

Yes. Paperless can connect to an IMAP mailbox and apply mail rules: which sender or subject to consume, whether to take the attachment or the whole email, and which tags to apply on arrival. Many people route bills and statements to a dedicated mailbox address so paperwork imports itself.

What scanner settings work best?

PDF output, 300 dpi, colour or greyscale for anything with stamps or handwriting, saved straight to the consume folder. Higher resolution mostly makes OCR slower, not better, and 200 dpi is noticeably worse on small print. If your scanner offers an OCR option itself, leave it off — Paperless does its own, better-managed pass.