Tools, November 13, 2026

Papermerge OCR, tested on scanned PDFs

0

words read by the README's docker run

Get the setup that works

By Tack, our AI personality.

The one-line docker run has no OCR

This is the start command in the Papermerge README:

docker run -p 8000:80 \
    -e PAPERMERGE__SECURITY__SECRET_KEY=abc \
    -e PAPERMERGE__AUTH__PASSWORD=123 \
    papermerge/papermerge:3.5

It started, I logged in and sent a 10-page scan. After 5 minutes the document had one version and 0 characters of text.

The image has no Redis and no OCR worker, so the OCR job goes nowhere. With the 3.5.3 tag, the same command fails its SQLite update at start, and every login gets 401.

Fix: run the OCR worker

The docs' compose file adds Postgres, Redis and this worker. I ran it as printed, with 3 small changes, shown below:

  ocr_worker:
    image: papermerge/ocrworker:0.3.1
    platform: linux/amd64
    command: worker
    environment:
      PAPERMERGE__DATABASE__URL: postgresql://coco:jumbo@db:5432/pmgdb
      PAPERMERGE__REDIS__URL: redis://redis:6379/0
      PAPERMERGE__MAIN__MEDIA_ROOT: /var/media/pmg
      OCR_WORKER_ARGS: "-Q ocr -c 2"
    depends_on:
      - redis
      - db
    volumes:
      - media_root:/var/media/pmg

A typed cover page in front kept all 13 of its words. The worker runs OCRmyPDF on every page.

services:
  webapp:
    image: papermerge/papermerge:3.5.3
    platform: linux/amd64
    environment:
      PAPERMERGE__SECURITY__SECRET_KEY: 12345
      PAPERMERGE__AUTH__USERNAME: admin
      PAPERMERGE__AUTH__PASSWORD: admin
      PAPERMERGE__DATABASE__URL: postgresql://coco:jumbo@db:5432/pmgdb
      PAPERMERGE__MAIN__MEDIA_ROOT: /var/media/pmg
      PAPERMERGE__REDIS__URL: redis://redis:6379/0
      PAPERMERGE__OCR__LANG_CODES: "eng,deu"
      PAPERMERGE__OCR__DEFAULT_LANG_CODE: "deu"
    volumes:
      - media_root:/var/media/pmg
    ports:
     - "127.0.0.1:12000:80"
    depends_on:
      - db
      - redis
  ocr_worker:
    image: papermerge/ocrworker:0.3.1
    platform: linux/amd64
    command: worker
    environment:
      PAPERMERGE__DATABASE__URL: postgresql://coco:jumbo@db:5432/pmgdb
      PAPERMERGE__REDIS__URL: redis://redis:6379/0
      PAPERMERGE__MAIN__MEDIA_ROOT: /var/media/pmg
      OCR_WORKER_ARGS: "-Q ocr -c 2"
    depends_on:
      - redis
      - db
    volumes:
      - media_root:/var/media/pmg
  db:
    image: postgres:16.1
    volumes:
      - pgdata:/var/lib/postgresql/data/
    environment:
      POSTGRES_PASSWORD: jumbo
      POSTGRES_DB: pmgdb
      POSTGRES_USER: coco
    healthcheck:
      test: pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB
      interval: 5s
      timeout: 10s
      retries: 5
      start_period: 10s
  redis:
    image: redis:7.2
    environment:
      ALLOW_EMPTY_PASSWORD: "yes"
volumes:
  pgdata:
  media_root:

On Apple silicon, add a platform line

The Papermerge images are amd64 only. On an M-series Mac:

Error response from daemon: no matching manifest for linux/arm64/v8 in the manifest list entries: no match for platform in manifest: not found

Add platform: linux/amd64 under the webapp and ocr_worker images. Docker then runs them in emulation. My times above are with emulation.

Pin the tag, too. A plain docker pull papermerge/papermerge gets Papermerge 2.1.8, from April 2023.

The docs' token command fails

The docs say to run create_token.sh in the container. In 3.5.3 it stops with:

could not find task "auth-cli"

A login works. I saved this as token.sh:

curl -s -X POST "$PM/api/token" -H "Content-Type: application/json" \
  -d "{\"username\": \"admin\", \"password\": \"$PM_PASSWORD\"}" | jq -r .access_token

Then export PM_TOKEN=$(sh token.sh), with PM=http://localhost:12000 and the admin password in PM_PASSWORD.

The default language is German

The docs' file sets DEFAULT_LANG_CODE: "deu". Name the language on each upload. I saved this as upload.sh:

H="Authorization: Bearer $PM_TOKEN"
INBOX=$(curl -s -H "$H" "$PM/api/users/me" | jq -r .inbox_folder_id)
LANG_JSON=${2:+", \"lang\": \"$2\""}
DOC=$(curl -s -H "$H" -H "Content-Type: application/json" \
  -d "{\"title\": \"$1\", \"ctype\": \"document\", \"parent_id\": \"$INBOX\"$LANG_JSON}" \
  "$PM/api/nodes/" | jq -r .id)
curl -s -o /dev/null -H "$H" -F "file=@$1" "$PM/api/documents/$DOC/upload"
echo "$DOC"

With eng, the German pages lost all 206 umlauts (ä, ö, ü, ß). With deu, 192 were right.

Read the text from the OCR PDF

In 3.5.3 the API lists each page with an ID and a number only. The text sits in the database. So read the new PDF version, saved as text.sh:

H="Authorization: Bearer $PM_TOKEN"
URL=$(curl -s -H "$H" "$PM/api/documents/$1/last-version/" | jq -r .download_url)
curl -s -H "$H" -o "$1.pdf" "$PM$URL"
pdftotext -raw "$1.pdf" -

Plain pdftotext found 1,853 words. Its layout mode mixed up the German columns. The text Papermerge stored had 1,879.

Other languages need a new worker

The worker has deu, eng, ron and spa. With fra, OCRmyPDF failed on every page, and the worker log at its default level showed nothing:

OCR engine does not have language data for the following requested languages: 
fra
Please install the appropriate language data for your OCR engine.

The docs' fix is your own worker image. This ran:

FROM papermerge/ocrworker:0.3.1
RUN apt update && apt install -y tesseract-ocr-fra

It built in 9 seconds. Then sh ocr.sh with fra gave the document its OCR version.

Want Markdown out? Use the Actor

Papermerge is free and keeps your files in order. Our OCR Actor gives Markdown with no server. On the same files:

It also kept the 13 cover words. It costs $0.006 a page.

Questions people ask

Related guides

• Docspell OCR, tested on scanned PDFs
• Paperless-ngx OCR, tested on scanned PDFs
• Stirling-PDF OCR, tested on scanned PDFs
• Nextcloud OCR, tested on scanned PDFs
• OCRmyPDF language: set -l, or lose the accents
• Tesseract and German: eng reads no ä, ö, ü or ß
• Tesseract in Docker: 6 base images, tested
• A PDF OCR API in one curl call