Paperless-ngx

Paperless-ngx takes the pile of paper on your desk – receipts, payslips, insurance letters, warranty cards you’ll need in three years and forget you kept – and turns it into a searchable digital archive that lives on your own server. Every page gets OCR’d on the way in. A built-in classifier watches how you’ve tagged past documents and starts guessing tags, correspondents, and document types on the next one, usually correctly.

What Paperless-ngx actually does

Every incoming file gets run through OCR, and the extracted text is indexed for full-text search across the whole archive, not just the filename. The part that trips people up if they’re coming from a plain scan-to-PDF habit is the tagging. There’s no fixed taxonomy to fill in by hand. Instead, a small classifier trains on documents you’ve already tagged and starts proposing tags, correspondents, and document types on its own. It’s rough for the first few dozen documents, then it clicks.

• OCR and full-text search on every page, not just the title
• Tag, correspondent, and document-type suggestions from a classifier trained on your own library, not a generic model
• A watched “consume” folder plus optional IMAP mailbox fetching, so a scanner or a phone app can feed it directly
• Barcode-based separation, so a whole stack of unrelated paperwork can go through the scanner in one pass
• Document version history and an audit trail
• A documented REST API and a workflow engine to auto-assign metadata on arrival

Is Paperless-ngx actually open source?

Yes, GPL-3.0, checked against the LICENSE file in the official repository rather than assumed. Paperless-ngx earns the “ngx” in its name honestly: the original Paperless project got forked into Paperless-ng by a solo maintainer, and when he stepped back in 2022, a group of contributors picked it up rather than let it die. Maintenance is now spread across a team instead of resting on one person’s free time, and it shows – releases land roughly monthly, and the project has passed 40,000 GitHub stars.

Installing Paperless-ngx with Docker

The official repository ships ready-made Compose files for three setups. SQLite is the simplest at two containers. PostgreSQL adds a dedicated database container once your library grows past hobby size. A Postgres-plus-Tika variant throws in Gotenberg and Apache Tika so Paperless-ngx can also chew through Word, Excel, and PowerPoint files by converting them to PDF first.

services:
  broker:
    image: docker.io/library/redis:8
    restart: unless-stopped
    volumes:
      - redisdata:/data
  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - 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
    env_file: docker-compose.env
    environment:
      PAPERLESS_REDIS: redis://broker:6379
volumes:
  data:
  media:
  redisdata:

Or skip typing it out and let the official install script set up the folder and files for you:

bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

1. Download the Compose files, or run the install script above, into their own folder.
2. Edit docker-compose.env to set a secret key and, if needed, your external URL.
3. Run docker compose up -d and wait for the containers to report healthy.
4. Create the first admin account: docker compose exec webserver python manage.py createsuperuser.
5. Drop a PDF into the consume folder and watch it get OCR’d and tagged on its own.

Pros and cons

• Real OCR and full-text search across the whole archive, not just filenames
• Tagging that actually learns your habits instead of forcing a rigid folder structure on you
• The consume folder and IMAP fetching make scanner and phone ingestion nearly hands-off
• An active community, roughly monthly releases, 40,000+ GitHub stars
• A real REST API if you want to script around it

• No encryption at rest – that part is entirely on you, at the disk or network layer
• Tag suggestions are only as good as what you’ve already tagged, so day one is rough going
• Office document support needs two extra containers, not a checkbox in a settings page
• No mobile app maintained by the core team, so you’re trusting third-party clients

Adding AI tagging on top

Paperless-ngx’s own tagging model learns from your library, not from a language model, but plenty of people go looking for an LLM add-on anyway. The most visible one is paperless-gpt, a separate MIT-licensed community project (not affiliated with the Paperless-ngx team, and it says so upfront) that talks to Paperless-ngx over its API to generate titles, tags, and correspondents, and can clean up OCR on messy scans. You don’t have to hand your documents to a cloud API to use it, either: point it at a local Ollama server instead of OpenAI and everything stays on hardware you already own, which fits the kind of homelab setup most people running Paperless-ngx already have.

Alternatives

Mayan EDMS covers similar ground but leans into heavier, enterprise-style workflow tools. Docspell targets the same single-user archive job with its own tagging approach. And if what you actually need is general file storage and sync, not OCR’d scan archiving, that’s a different tool entirely – our Nextcloud fiche covers plain file storage rather than document-specific OCR and tagging.

Frequently asked questions

Is Paperless-ngx free? Yes, GPL-3.0, no paid tier, no account required.

Does it need an internet connection? No. OCR, tagging, and search all run locally. The only reason to reach outside your network is an optional AI add-on pointed at a cloud API instead of a local model.

Can it read handwriting? Not reliably, not with the built-in Tesseract-based OCR anyway. LLM-based OCR add-ons do noticeably better on handwriting and messy receipts, at the cost of extra setup.

Official documentation lives at docs.paperless-ngx.com, the source and license are on GitHub, and a public demo (login demo/demo) is available at demo.paperless-ngx.com if you want to poke around before committing a server to it. For the hardware side of running this alongside other self-hosted apps, see our homelab setup guide.