Most homelab stacks start with the fun stuff, media servers, dashboards, maybe a VPN. The boring problem that never goes away is paper: tax documents, insurance paperwork, warranty receipts, kids’ school forms, the occasional letter that actually matters. Paperless-ngx exists to solve exactly that, and it’s one of the few self-hosted apps where the payoff shows up the first week instead of months later. Scan something in, and from then on you can find it by typing a word that appears anywhere in it, not by remembering which folder you filed it under three years ago.
What Paperless-ngx actually does
Paperless-ngx is a document management system built around one core idea: every document gets OCR’d on the way in, so its full text is searchable forever after, regardless of whether it started as a scanned image or a native PDF. Under the hood it’s a Django web app backed by a database (SQLite for small single-user setups, Postgres if you want something that scales better or you’re already running Postgres for other apps anyway), a task queue backed by Redis for the actual consumption and OCR work, and a document storage layer that keeps both the original file you fed it and a searchable, OCR’d archive version side by side.
The project is a community-maintained continuation of the original Paperless, which went unmaintained; it’s been the active, actually-updated version for years now and is what basically everyone means when they say “paperless” in a self-hosted context today.
The consumption folder is the whole workflow
Everything in Paperless-ngx starts with the consumption directory, a watched folder that the app polls (or watches via inotify) for new files. Drop a PDF, PNG, JPG, or a handful of other supported formats into it, and a background worker picks it up, runs OCR if the text layer isn’t already there, extracts whatever text it can, and files the result away. That’s the entire ingestion model, there’s no “upload” button you have to click for the bulk of your documents, just a folder.
In practice that folder gets fed from a few different directions:
- A network scanner with “scan to folder” (SMB/FTP) pointed directly at the consumption directory, the cleanest path if your scanner supports it.
- A flatbed or sheet-fed scanner hooked to a desktop, with the resulting PDFs synced over to the consumption folder afterward.
- A phone, using Paperless-ngx’s own mobile app or a general-purpose “scan with camera” app configured to drop its output into a synced folder. Phone-camera scans OCR noticeably worse than a real scanner on noisy or skewed pages, worth knowing before you commit to phone-only scanning for anything you’ll actually need to search later.
- Email, via the built-in mail fetcher, point it at an IMAP mailbox (or a dedicated folder within one) and it’ll pull attachments in automatically, useful for e-receipts and PDF statements that already arrive as email attachments instead of paper.
OCR and why searchability is the actual feature
The OCR step uses Tesseract under the hood, and it’s genuinely the thing that makes this whole system worth running instead of just dumping scanned PDFs into a folder in Nextcloud. A scanned image, by itself, is just a picture of text to a computer, nothing in it is searchable. Paperless-ngx’s OCR pass extracts the actual text and buries it as an invisible text layer in the archived PDF, so a full-text search for “deductible” or a specific policy number turns up the right document instantly, even in a stack of a few thousand scans.
Install the language packs for whatever language your documents are actually in, OCR accuracy for an English-only install trying to parse a document in another language is bad enough to be useless. If you deal with mixed-language paperwork, you can configure multiple languages and it’ll try each.
OCR is genuinely one of the more CPU-intensive things you’ll run in a typical homelab, noticeably more than something like Pi-hole or Uptime Kuma, though far less than video transcoding. Budget real CPU time for the consumer worker, and if you’re bulk-importing a backlog of hundreds of old scans at once, expect that initial run to take a while and to peg a core or two for a stretch. Day-to-day ingestion of a handful of new documents a week is a non-event on almost any homelab hardware.
Classification: correspondents, document types, tags, and storage paths
Where Paperless-ngx earns its name over “a folder of searchable PDFs” is the classification layer on top. Three core concepts organize everything:
- Correspondents are who the document is from or to, your bank, your insurer, a specific person.
- Document types describe what it is, invoice, statement, letter, receipt.
- Tags are freeform labels you can stack arbitrarily, tax-2026, warranty, needs-action, whatever fits your own filing instincts.
Paperless-ngx includes a built-in machine-learning classifier that learns from how you’ve tagged documents in the past and starts suggesting (or, if you let it, auto-assigning) correspondents, types, and tags on new incoming documents based on patterns it’s picked up. It’s not magic, it needs a reasonable number of manually-tagged examples before its suggestions get genuinely useful, but once it’s past that point it meaningfully cuts down the manual triage work on routine, recurring documents like monthly statements.
On top of tags, storage paths let you define a templated folder/filename structure (using the document’s metadata, correspondent, date, type) that the underlying files get organized into on disk. Useful if you ever want to browse the raw files outside the web UI, or if you’re nervous about Paperless-ngx’s database being the only place that organization lives.
Where to run it and what it needs
Paperless-ngx ships as a Docker Compose stack (web app, Redis, and optionally Postgres as separate containers), and that’s the path of least resistance, the project’s own documentation is built around it. It fits fine in an LXC with Docker inside, or as a straightforward Compose deployment alongside whatever else you’re already running. For a single household’s document volume, a couple of CPU cores and a gig or two of RAM for the always-on services is plenty, the real resource spike is transient, during active OCR consumption, not sitting idle.
Put it behind your existing reverse proxy with real TLS, same as anything else holding documents you don’t want sitting on an open port. If you’re running an SSO/forward-auth layer like Authentik or Authelia in front of your stack, Paperless-ngx supports header-based remote user auth cleanly, so you can gate it behind your IdP rather than maintaining a separate login, unlike a password vault, this one doesn’t need to stay independent of your identity layer.
Backup here is not optional, and it’s not like backing up a media server
This is the one point worth being blunt about. If your Plex library disappears, that’s annoying and re-rippable. If your Paperless-ngx archive disappears and you’d already shredded the paper originals on the assumption the scan was good enough, you’ve actually lost the document, not just the convenience of having it searchable. Treat this backup with the same seriousness you’d give a password vault, not the same shrug you might give a media server.
Three things need to survive, together, as a consistent set: the database (SQLite file or Postgres dump), the media directory holding both the original and archived versions of every document, and the export of your actual configuration if you’ve invested time into correspondents, types, and tags. A hypervisor-level VM backup covers the box dying, but pair it with an app-level backup (Restic or Borg, or Paperless-ngx’s own built-in document exporter run on a schedule) that you’ve actually tested a restore from. The export/import path (document_exporter/document_importer) is also the sanest way to move a Paperless-ngx instance between hosts if you ever rebuild.
On the shred-the-original question: that’s a decision only you can make based on what the documents are and what retention requirements apply to you, this isn’t legal advice and requirements vary by document type and jurisdiction. What’s universally true regardless of that decision is that a scan you’re relying on as your only copy of something deserves a tested backup before you treat the paper as disposable.
Bottom line
Paperless-ngx is the rare self-hosted app that pays for its setup time almost immediately, once a document is in and OCR’d, you stop thinking about where you filed it and start just searching for it. The consumption-folder workflow makes ingestion close to zero-friction once you’ve got a scanner or a mail fetcher feeding it, and the correspondent/type/tag classification (with the machine-learning assist once it’s trained) keeps a few thousand documents actually navigable instead of becoming a second junk drawer. The part that deserves real attention, more than with most other apps in this category, is backup: a scanned document you’re trusting as your only copy of something is exactly the kind of data where “I’ll back it up eventually” is the wrong answer.