Bills, contracts, warranties, medical reports, tax receipts: every household accumulates paper that must be kept for years and that, when you need it, can never be found. Paperless-ngx is an open source application that turns this archive into a searchable database: you scan a document, the system extracts its text with OCR, classifies it and makes it searchable by the words it contains, not just by file name.
How the flow works
The heart of Paperless-ngx is the consume folder. Anything placed in it is picked up automatically:
- the file (PDF, image, and also emails or office documents with the optional components) is read;
- OCR, based on Tesseract via OCRmyPDF, recognises the text;
- an archive version is created as PDF/A with selectable text, while the original is kept as well;
- matching rules assign tags, correspondent and document type;
- the original file is removed from the consume folder.
The folder can be shared on the network, so the scanner or phone can save directly into it. Many office scanners can send files to a shared folder: this is the most convenient setup, because a single button press is enough.
Installation and OCR language
The project provides ready-made Docker Compose files, with PostgreSQL or MariaDB as the database and Redis as the queue. A frequently overlooked detail is the OCR language: for Italian documents it must be set explicitly, otherwise accents and words are poorly recognised.
environment:
PAPERLESS_OCR_LANGUAGE: "ita+eng"
PAPERLESS_TIME_ZONE: "Europe/Rome"
PAPERLESS_FILENAME_FORMAT: "{{ created_year }}/{{ correspondent }}/{{ title }}"
The file name format determines how documents are organised on disk. It is not essential, because you nearly always work from the interface, but it keeps the archive readable even without the application: a huge advantage if one day you decide to leave it.
The four dimensions of the archive
Paperless-ngx organises documents along several independent axes, and it helps to know which one to use for what:
| Field | Example | Use |
|---|---|---|
| Correspondent | energy supplier, bank, doctor | who issued the document |
| Document type | bill, contract, warranty | what it is |
| Tags | home, car, tax 2025 | cross-cutting themes, more than one allowed |
| Storage path | Home/Utilities | where the file ends up on disk |
On top of these there are custom fields, for example an expiry date or an amount, useful for warranties and insurance.
Automating classification
For each correspondent, type and tag you can choose a matching algorithm:
- exact word or any word: the document gets the tag if it contains a given term, for example the customer number of a contract;
- regular expression: for more complex patterns;
- auto: Paperless-ngx learns from manual classifications and suggests assignments for similar documents.
The approach that works best is to start with auto and patiently correct the first documents: after a few dozen examples per category the suggestions become reliable. For critical cases, such as a utility's customer code, an exact rule is safer.
Workflows also let you act at ingestion time: for example, every file coming from a certain subfolder gets the "to review" tag.
Ingesting email too
Paperless-ngx can check a mailbox via IMAP and import attachments that meet certain criteria, such as sender or subject. It is ideal for invoices that only arrive electronically: you create a rule per sender and the document enters the archive with no manual step.
Scanning well
OCR quality depends on the scan:
- 300 dpi is the usual compromise between legibility and size;
- black and white or greyscale is enough for most text documents;
- a scanner with an automatic duplex feeder saves a lot of time;
- a phone scanning app is fine for occasional documents, as long as it straightens the page.
A useful trick: a sheet with a special separator code (so-called barcode pages) lets you scan a stack of documents into a single file and have it split automatically.
Backup and export
Paperless-ngx includes the document_exporter tool, which exports originals, archive versions and metadata to a folder. It is the safest way to make consistent backups and to migrate to a new installation:
docker compose exec webserver document_exporter ../export
The export folder should then be copied by your normal backup system, encrypted, and also kept off-site. Remember that the archive contains highly sensitive data: identity documents, health and financial records. It is better not to expose it to the Internet and to reach it from outside only through a private network.
In short
- Paperless-ngx makes every document searchable thanks to OCR and the PDF/A version.
- A consume folder shared with the scanner makes the flow almost automatic.
- Correspondents, types, tags and custom fields organise the archive on several axes.
- Automatic matching improves with early manual corrections.
- The export command is the basis for consistent backups and migrations.
