Paperless-ngx

Last reviewed Aug 22, 2026 · 683 words

Paperless-ngx turns a shoebox of paperwork into a searchable archive: drop a scan in a folder, and OCR, date detection, tagging, and full-text indexing happen without you. The software is mature and the setup is honest about its needs — about 2 GB of RAM while OCR runs and a Redis container alongside. The part nobody tells you: the tool is 20% of going paperless. The other 80% is a scanning habit and a tagging scheme you can still explain in a year.

The stack, minus the surprises

services:
  broker:
    image: redis:7-alpine
    restart: unless-stopped
  paperless:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    depends_on: [broker]
    ports:
      - "8000:8000"
    environment:
      - PAPERLESS_REDIS=redis://broker:6379
      - PAPERLESS_URL=https://paperless.example.com
      - PAPERLESS_OCR_LANGUAGE=eng
    volumes:
      - ./data:/usr/src/paperless/data
      - ./media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    restart: unless-stopped

Redis is not optional — it queues the OCR tasks. The default SQLite database is genuinely fine for a household archive; move to Postgres only if you reach tens of thousands of documents or multiple heavy users. Set PAPERLESS_OCR_LANGUAGE for every language your paper arrives in (eng+deu syntax), because OCR in the wrong language produces text that indexes but never matches a search — a failure you discover months later, one missing document at a time.

The consume folder is the whole workflow

Paperless watches ./consume and ingests anything that lands there. Everything about going paperless successfully is about shortening the path from "paper in hand" to "file in that folder":

• Network scanner: point its scan-to-SMB/FTP target straight at the consume folder. This is the gold standard — one button on the scanner, no computer involved.
• Phone: any scanner app that can save into a synced folder works; Syncthing syncing your phone's scans directory to ./consume makes the phone a first-class scanner.
• Email: Paperless can poll a mailbox and ingest attachments — set a rule for the utility company's PDF invoices and they file themselves.

Scan, confirm it appeared, shred the original. If you keep the paper "just in case," you now maintain two filing systems, which is worse than either alone.

Tags: fewer than you think, plus one inbox

Paperless gives you tags, correspondents, and document types, and its matching learns to apply them automatically. The failure mode is building a 60-tag taxonomy in week one that you abandon by week six. What holds up: 10–15 tags for why you'd retrieve this (tax, insurance, warranty, medical, house, car), correspondents for who sent it, and document types kept to a five-item list (invoice, statement, contract, letter, receipt). Add an inbox tag applied automatically to every new document, and do a weekly two-minute triage where you confirm auto-filing and clear the inbox. The matching engine gets noticeably good after 50–100 corrected documents — front-load your corrections and it repays you for years.

Back up with the exporter, not a folder copy

The originals in ./media are only half the system — the database holds tags, correspondents, dates, and learned matching. The supported backup is the built-in exporter, which writes both:

docker compose exec paperless document_exporter ../export

Run it nightly via cron, ship ./export off-site, and you can rebuild an identical instance from scratch with document_importer. Because the export is plain PDFs plus JSON metadata, it doubles as your escape hatch from Paperless itself — the own-your-data test passes with full marks. The complete routine, including a restore drill, is in the Paperless-ngx guide.

What I'd do

The compose stack above on any 4 GB box, OCR languages set on day one, scanner button wired to the consume folder, the small-taxonomy-plus-inbox scheme, and the nightly exporter. Feed it your current paper for two weeks before back-scanning the archive boxes — habit first, backlog second. Six months in, "where's the boiler warranty" becomes a four-second search, and that is the moment the shredder pays for itself.