How to Use Paperless-ngx: The Beginner's Guide (First Install, First Document, OCR, and the Backup Rule)
CodexFuse Team · 2026-10-31T03:57:27.257Z · 12 min read
Learn how to use Paperless-ngx: install it with Docker, ingest your first document with the consume folder, let OCR make it searchable, and back up the archive the right way.
If your desk has a growing pile of receipts, bills, and contracts that you can never find when you need them, learning how to use Paperless-ngx is the fastest way to turn that pile into a searchable archive you own. Paperless-ngx is a free, open-source document management system you install on your own server or home machine. You feed it scans and PDFs, it runs OCR on anything that is not already searchable text, and from then on you find any document by typing a word from it.
This guide walks you from a fresh install to your first searchable document, explains the tagging system that keeps everything organized, and finishes with the backup habit that keeps the archive safe. If the paper has not been scanned yet, a document scanner turns your phone into the scanner that feeds the archive. The archive itself runs in Docker containers, so our Docker beginner guide covers the one prerequisite you need first.
How do you use Paperless-ngx for the first time?
You install it with the official install script, create an admin account, drop your first document into the watched consume folder, wait for the system to OCR and index it, and then find it with the search bar. The five-step arc below is the whole beginner journey.
- Install. Run the official installation script on a Linux machine with Docker and Docker Compose (details below), or download one of the ready-made Docker Compose templates.
- Create your admin account. Open http://127.0.0.1:8000 in your browser and you will be prompted to create the superuser account.
- Add your first document. Drop a PDF or a scanned image into the consume folder, or drag-and-drop it into the web UI.
- Run your first search. Once the consumer finishes OCR and indexing, type a word from the document into the search bar and watch it appear.
- Set the backup rule. Back up the data folder, the media folder, and the database together — before the archive grows.
How do I install Paperless-ngx?
You install Paperless-ngx by running the project's official install script, or by downloading one of its Docker Compose templates and starting them yourself. The official setup documentation recommends the install script for most first-timers: it asks a few configuration questions, then creates the files, pulls the images, starts the containers, and creates your superuser account.
The script comes straight from the project's own documentation:
bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"Prerequisites are Docker and Docker Compose on a Linux machine. If piping a script from the internet into your shell makes you nervous, the docs say the same thing: inspect the script first.
| Install route | Best for | What it asks of you |
|---|---|---|
| Installation script | First-timers who want it running fast | Answer guided prompts; the script builds everything |
| Docker Compose templates | Users who want control over the compose files | Download a docker-compose.*.yml plus docker-compose.env and .env, edit paths, then docker compose up -d |
| Bare metal | Advanced setups and packagers | Manual install of Python, Redis, PostgreSQL, Tesseract, and friends |
For new installations the docs recommend PostgreSQL as the database backend. A SQLite template exists for quick tries (docker-compose.sqlite.yml in the project's /docker/compose directory), but Postgres is the recommended home for a real archive. After installation, the app listens on port 8000 — http://127.0.0.1:8000 on the machine itself. If you are putting it on a VPS rather than a home machine, read what is VPS hosting to pick the right kind of server for it.
What is the consume folder in Paperless-ngx?
The consume folder is a directory on your host that Paperless-ngx watches continuously: anything you drop into it is picked up automatically, OCR'd if needed, classified, and filed into the archive — and the original file is moved out of the folder on success. In the default compose setup it is mounted at /usr/src/paperless/consume inside the container and mapped to a ./consume directory on your host.
Here is what happens to one document, a scanned power bill named bill-march.pdf:
- You copy bill-march.pdf into ./consume/.
- The consumer (a background worker process) notices it, runs Tesseract OCR because the scan is an image, and reads the text.
- Matching rules kick in: a tag with "match any of: power, electric" auto-applies, the correspondent "City Power" is detected, and the document type is set to Invoice.
- The file is stored by its hash under media/documents/originals/ so duplicates are impossible, a thumbnail is generated, and the OCR'd text is indexed.
- bill-march.pdf disappears from ./consume/. Type "power bill march" in the search bar and it is there.
The consume folder is the most powerful ingest path, but not the only one. The web UI accepts drag-and-drop for occasional uploads. Mobile scan apps (Paperless Mobile on Android, several iOS clients through the REST API) snap a photo, auto-crop and auto-deskew it, and upload it — the same workflow as a cloud scan app, landing on your own server. A document scanner with a network destination can scan straight to the consume share or to an email address Paperless polls. And for the paperless mail you already get, Paperless polls an IMAP inbox: Settings, then Mail, then Add IMAP account, and attachments matching your size, sender, and subject rules are ingested automatically.
How does Paperless-ngx OCR and tagging work?
Paperless-ngx runs Tesseract OCR on every document that is not already searchable text, then organizes the result under three classification dimensions: tags, correspondents, and document types. Tags are multi-valued labels like taxes, healthcare, or warranty. A correspondent is the issuer or sender — the bank, the landlord, the city. A document type is a single-valued category such as Invoice, Receipt, Statement, Letter, or Contract.
You do not have to tag everything by hand. Each tag, correspondent, and type can carry matching rules: a tag with "match any of: invoice, facture" auto-applies to every document whose OCR'd text contains those words. The matching algorithms are exact, any word, all words, regex, fuzzy, and auto, which uses a machine-learning classifier. That classifier is off by default; after a few hundred manually classified documents it can learn your habits and start suggesting tags itself.
One setting matters before your first document: Tesseract defaults to English. If your documents are written in another language, set PAPERLESS_OCR_LANGUAGE to the right language code (an example setup uses eng+fra for English plus French) — the official docs recommend setting it to the language most of your documents use. The OCR engine in the Docker image supports over a hundred languages.
How do I back up my Paperless-ngx archive?
You back up three things together: the data/ directory (the search index and configuration), the media/ directory (the original document files in their original format), and the database (titles, tags, correspondents, dates — PostgreSQL metadata). Back up only one of them and you get an archive you cannot fully restore, which is why the backup rule is: data, media, and database, together, before the archive grows.
Paperless-ngx ships a one-command document exporter for restorable backups:
docker compose exec webserver \
document_exporter ../export --no-progress-bar --compare-checksumsThis dumps the entire archive plus its JSON metadata into the ./export/ folder (mounted at /usr/src/paperless/export) in a format Paperless can re-import later with document_importer. Keep a copy of that export folder off the machine — a second drive, a backup service, anywhere but the server it came from. Because OCR adds a separate searchable PDF/A copy next to each original, plan on 1.2 to 1.5 times the storage of your originals: a few gigabytes covers a household archive of several years, tens of gigabytes is normal for a small business.
Since the archive lives on your server, lock the server down too: generate keys with our SSH key generator and use key-only login before you open anything to the network.
Paperless-ngx vs Nextcloud: which one do I need?
Choose Paperless-ngx when you want an archive: a place where finished documents live so you can find them again in three years. Choose Nextcloud when you need collaboration on living documents — real-time co-editing, versioned edits, shared workspaces. Paperless-ngx is an archive, not a collaboration tool, and trying to run team workflows on it will frustrate you. For "save the PDF the bank sent and find it again in three years," Paperless is exactly the right tool.
Does Paperless-ngx have a mobile app?
Paperless-ngx has Paperless Mobile for Android, and several iOS clients connect through its REST API. The workflow mirrors a cloud scan app: snap a photo of the document, the app auto-crops and auto-deskews it, and it uploads straight into your archive where the consume pipeline takes over. Nothing passes through a third-party cloud.
Paperless-ngx beginner mistakes to avoid
Most first-week pain comes from the same handful of missteps. The table below is the short list.
| Mistake | What happens | Do this instead |
|---|---|---|
| Consuming documents before setting the OCR language | Non-English documents get poor OCR and stay badly searchable | Set PAPERLESS_OCR_LANGUAGE to your documents' language first, then consume |
| Backing up only the media folder | You have the files but no titles, tags, or search index to restore | Back up data/, media/, and the database together; use document_exporter |
| Exposing port 8000 directly to the internet | Your archive's login page is reachable by anyone | Bind to 127.0.0.1 behind a reverse proxy; set PAPERLESS_URL to your domain or logins fail CSRF checks |
| Dumping thousands of files into consume at once | A long OCR queue and a confusing first impression | Start with a handful of documents, verify the tagging, then batch the rest |
| Expecting a team workspace | No co-editing, no shared live documents | Use Paperless as the archive and a tool like Nextcloud for living documents |
Sources
- Paperless-ngx official setup documentation (docs.paperless-ngx.com/setup) — the installation script, Docker Compose templates, PostgreSQL recommendation, the consume-folder mount, PAPERLESS_OCR_LANGUAGE guidance, and reverse-proxy notes.
- Amir Eslampanah, "Paperless-ngx: a self-hosted document archive with OCR" — the compose-stack example, the consume pipeline, tags/correspondents/types and matching rules, email ingest, the backup trio, and the 1.2–1.5x storage rule.
- dev.to API quickstart for Paperless-ngx — the SQLite compose template, the createsuperuser step, Tesseract's 100+ languages, and the matching algorithms.
- Railway's Paperless-ngx deploy page — the 3.3.0 Postgres/Redis stack and the PAPERLESS_URL-must-match-the-domain CSRF note.
- Mustafa Erbay's Paperless-ngx tutorial — the OCR-archive framing and consume-folder auto-ingest.
Frequently asked questions
Is Paperless-ngx really free?
Yes. Paperless-ngx is a community-supported open-source project with no license fee; the only cost is the machine it runs on, whether that is your own computer or a small VPS.
How much storage does Paperless-ngx need?
Plan on roughly 1.2 to 1.5 times the size of your original documents, because OCR adds a searchable PDF/A copy next to each original. A household archive of several years fits in a few gigabytes.
Can I access Paperless-ngx from outside my home network?
Yes, with a reverse proxy such as Caddy pointing at the app's port 8000. Set PAPERLESS_URL to your public domain in the environment, otherwise the login will fail CSRF checks.
Which languages does the OCR support?
The built-in Tesseract engine supports over a hundred languages. Set PAPERLESS_OCR_LANGUAGE to the language most of your documents are written in before you consume your first files.
If I stop using Paperless-ngx, do I lose my documents?
No. Originals are stored in media/documents/originals/ in their original format, and the document exporter dumps the whole archive plus JSON metadata that Paperless can re-import — you are never locked in.
