Paperless-ngx OCR: Settings That Fix Missing Text, Wrong Languages, and Bloated PDFs
Paperless-ngx OCR is Tesseract running through OCRmyPDF inside the Paperless container. Out of the box it reads English, skips PDFs that already contain text, cleans and deskews scans, and stores a PDF/A archive copy next to your original. When search misses words you can see on the page, the cause is usually one of four settings: the OCR mode, the language list, the image cleanup options, or the fact that existing documents were processed under older settings and never re-read.
This guide covers those settings as they work in the current v3 releases, how to re-run OCR on documents you already have, and what to do when Tesseract is simply the wrong tool for a page. If you are still setting up the server, start with the Paperless-ngx Docker tutorial or the Synology guide and come back once documents are flowing.
How the OCR step fits into consumption
When a file lands in the consume folder or is uploaded, Paperless picks a parser by file type. PDFs and images go to the built-in Tesseract parser, which hands the file to OCRmyPDF. OCRmyPDF optionally runs unpaper to clean the image, corrects skew and rotation, runs Tesseract, and writes a text layer into a new PDF.
Paperless then keeps up to two files per document:
- The original, exactly as you supplied it. It is never modified.
- The archive version, a PDF/A file with the OCR text layer. The web viewer shows this one when it exists.
The extracted text is also saved in the database, which is what full-text search and matching rules run against. That detail matters: if the text in the database is poor, tags and correspondents assigned by matching rules will be poor too, no matter how good the archive PDF looks.
Office files (DOCX, ODT) and email follow different paths through Tika and the mail parser, so the OCR settings below mostly apply to scans, photos, and PDFs.
PAPERLESS_OCR_MODE: when OCR runs at all
PAPERLESS_OCR_MODE has four values in current releases:
| Mode | What it does | Use it when |
|---|---|---|
auto (default) |
Checks for embedded text with pdftotext. If enough text is found, OCR is skipped for that document. Otherwise OCR runs normally. | You receive a mix of born-digital PDFs and scans. This is the right default for most archives. |
redo |
OCRs every page and tries to replace any existing text layer. Also OCRs born-digital PDFs. | Your scanner or a third-party tool already embeds OCR text, and that text is bad. |
force |
Rasterizes every page, turning existing text into an image, then adds a fresh OCR layer. | Nothing else produces usable text, for example PDFs with broken font encodings. |
off |
Never runs Tesseract. PDFs get text from pdftotext only. Images get no text. | Your input is entirely born-digital and you want to save CPU. |
Two practical warnings. force makes files noticeably larger and the text less sharp when zoomed, because vector text becomes pixels. And redo disables deskewing and downgrades clean-final to clean, since those steps would change the page images under an existing layout.
If you are on a 2.x release, the names differ: the old default was skip, and archive behavior was controlled by skip_noarchive and PAPERLESS_OCR_SKIP_ARCHIVE_FILE. Check the docs for your exact version before copying settings between instances.
PAPERLESS_ARCHIVE_FILE_GENERATION: whether an archive PDF is created
In v3, whether Paperless writes a PDF/A archive is a separate decision, set by PAPERLESS_ARCHIVE_FILE_GENERATION:
auto(default) creates archives for scanned images and image-only PDFs, and skips them for born-digital PDFs that already contain text.alwayscreates an archive whenever the parser supports it.neverstores only the original. You save disk space, and the viewer shows the original file.
Plain text, email, and HTML never get an archive. DOCX and ODT always get a PDF rendition from Tika, because the browser cannot display them otherwise.
For a home or small-office archive, auto is a sensible balance. Choose always if you want every document stored in one long-term format, which some retention policies prefer.
Languages: PAPERLESS_OCR_LANGUAGE and PAPERLESS_OCR_LANGUAGES
These two settings are easy to confuse, and the difference is where most “OCR reads gibberish” reports come from.
PAPERLESS_OCR_LANGUAGE(singular) tells Tesseract which language models to use. It takes three-letter codes joined with+, such asdeu+eng. The default iseng.PAPERLESS_OCR_LANGUAGES(plural) installs extra Tesseract language packs when the Docker container starts. The image ships with English, German, Italian, Spanish, and French. Anything else has to be installed here first.
A Romanian and English setup, for example, looks like this in docker-compose.env:
PAPERLESS_OCR_LANGUAGES=ron
PAPERLESS_OCR_LANGUAGE=ron+eng
Watch the separators. The install list is space-separated and uses Debian package spelling, so Traditional Chinese is chi-tra there. The OCR language setting uses Tesseract’s spelling, so the same language is chi_tra. Mixing those up is a common reason a container starts fine but OCR falls back to garbage.
Also keep the list short. Tesseract tries each listed language, so deu+eng+fra+ita+spa on every page costs real CPU time on a NAS and often lowers accuracy on short fields. List the languages you actually receive. The install option also must not be used in rootless containers, so on those you need to build an image with the language packs included.
Image cleanup: clean, deskew, rotate, DPI
These settings decide what Tesseract sees. All are on by default except where noted.
PAPERLESS_OCR_CLEAN:clean(default) runsunpaperbefore OCR but keeps your original images in the output.clean-finalalso uses the cleaned images in the archive PDF.noneskips cleaning, which can help with photos and colored backgrounds that unpaper over-processes.PAPERLESS_OCR_DESKEW: straightens slightly tilted scans. Defaulttrue.PAPERLESS_OCR_ROTATE_PAGESandPAPERLESS_OCR_ROTATE_PAGES_THRESHOLD: fix pages scanned sideways or upside down. The threshold defaults to12. Raise it toward15if correct pages get flipped. Lower it if sideways pages are left alone, but values near2rotate pages that were fine.PAPERLESS_OCR_IMAGE_DPI: only a fallback for images without DPI metadata, such as some phone photos. Set it to your scanner’s real resolution. Tesseract does best on text scanned at around 300 DPI, so a scanner set to 150 DPI to save space is often the hidden cause of poor results.
Speed and size: OCR_PAGES and OCR_OUTPUT_TYPE
PAPERLESS_OCR_PAGES limits OCR to the first N pages. Setting it to 1 is a good trade on low-power hardware if most of your documents identify themselves on page one, but text on later pages will not be searchable.
PAPERLESS_OCR_OUTPUT_TYPE defaults to pdfa (PDF/A-2b). Use pdfa-1, pdfa-2, or pdfa-3 if a records policy names a version, or pdf to change the file as little as possible.
Passing extra options to OCRmyPDF
Anything OCRmyPDF supports can be passed with PAPERLESS_OCR_USER_ARGS as a JSON object. Option names use underscores instead of dashes, booleans are lowercase, and strings use double quotes:
PAPERLESS_OCR_USER_ARGS={"optimize": 1, "invalidate_digital_signatures": true}
invalidate_digital_signatures lets OCRmyPDF process signed PDFs that it would otherwise refuse. Only use it if the original signed file, which Paperless keeps untouched, is the copy you rely on for the signature. Test any new argument on a few documents first: an incompatible combination can stop consumption entirely, and the Paperless docs warn that this setting should only be changed by trusted admins.
Re-running OCR on documents you already have
Changing a setting only affects new documents. To apply it to existing ones you have two options.
In the web UI, open the document and use the Reprocess action. This is the right tool for a handful of files, for example after adding a language pack.
For many documents, use the document_archiver management command. With the standard Docker Compose setup:
# one document
docker compose exec webserver document_archiver --overwrite --document 1234
# every document without an archive version yet
docker compose exec webserver document_archiver
Without --overwrite, the archiver only creates archive files that do not exist yet. With it, it re-OCRs according to your current settings. On a large archive combined with redo mode this can run for many hours, but you can stop it and it picks up where it left off. Encrypted PDFs fail every time and are skipped.
Take an export with document_exporter before a bulk run, as described in our Paperless-ngx tips.
Symptom and fix list
| Symptom | Likely cause | What to change |
|---|---|---|
| Scans have no searchable text | Mode is off, or the scanner embedded an empty or junk text layer and auto trusted it |
Use redo, then reprocess the affected documents |
| Accented letters come out wrong | Language model missing | Add it to PAPERLESS_OCR_LANGUAGES and PAPERLESS_OCR_LANGUAGE |
| Container starts, OCR still poor after adding a language | Wrong spelling (chi-tra vs chi_tra) |
Use dashes in the install list, underscores in the OCR language |
| Pages appear rotated wrongly | Rotation threshold too low or too high | Adjust PAPERLESS_OCR_ROTATE_PAGES_THRESHOLD |
| Archive PDFs much bigger than originals | force mode or clean-final |
Switch to auto or redo, and clean |
| Long PDFs block the queue on a NAS | Every page is OCRed | Set PAPERLESS_OCR_PAGES |
| Large photos have missing text and a warning in the log | Image above the pixel limit | Downscale at capture, or raise PAPERLESS_OCR_MAX_IMAGE_PIXELS only for trusted input |
When Tesseract is the wrong tool
Tuning gets clean printed scans close to perfect. It does not make Tesseract good at handwriting, dense tables, faded thermal receipts, or photos taken at an angle under poor light. We go into why in why OCR is so bad on some documents.
Paperless has two built-in ways around that. The first is remote OCR, currently limited to Azure AI Document Intelligence, which is a paid service with a free tier. Set PAPERLESS_REMOTE_OCR_MODE=workflow_only and only documents matched by a workflow with a Remote OCR action leave your server. Everything else stays on local Tesseract.
The second is a workflow webhook to an external service. That is how OCRskill fits in: Paperless keeps doing local OCR for search, while OCRskill reads the page with a vision model and returns the document type, correspondent, issue date, and specific fields that Paperless writes back as metadata. The setup is in the archive tutorial.
A sensible order to work in
Start with languages, because they are the most common cause of bad text and the cheapest to fix. Then check that your scanner is set to around 300 DPI and is not embedding its own weak OCR layer; if it is, switch to redo. Leave cleaning, deskew, and rotation at their defaults until a specific batch of documents proves otherwise. Reprocess a sample, compare the text in the document details view, and only then run the archiver across everything. Settings changed in a hurry and applied to the whole archive at once are much harder to undo than the ten documents you tested first.
