Skip to main content

paperless-cf-ocr

A Paperless-ngx 3.x (3.0.5+) parser plugin that OCRs scanned documents with vision language models on Cloudflare Workers AI, called through Cloudflare AI Gateway. It replaces Tesseract's text with a much more accurate transcription. It reads handwriting, form fields and degraded copies. Paperless keeps everything else: thumbnails, searchable archive PDFs, workflows and AI suggestions.

  • Works with native and Docker installs, with no custom Paperless image and no sidecar service.
  • Default model: Qwen 3.8 27B (@cf/qwen/qwen3.8-27b). Any Workers AI vision model, or third-party models routed through the gateway, can be selected.
  • Confidence-aware. Each page gets a confidence score from token probabilities. Pages the model is unsure about can optionally be re-read by a second model, such as Claude Sonnet 5.5.
  • Asked not to guess. The transcription prompt tells the model to write [illegible] for unreadable text instead of making it up. In testing, models without this rule invented plausible text, including a wrong drug name on a medical form.
  • Reuses Paperless's AI settings when they already point at the same AI Gateway.

Third-party plugins are not supported by the Paperless-ngx maintainers. Reproduce any Paperless problem with the plugin removed before reporting it upstream.

How it works

  1. Paperless picks this parser for PDFs and images (score 30, above Tesseract's 10 and the built-in Azure OCR's 20) whenever the plugin is configured. With PAPERLESS_REMOTE_OCR_MODE=workflow_only, it is only used for documents a workflow marks for remote OCR, as for any remote parser.
  2. PDF pages are rendered at 200 dpi (at most 2048 px) and images are normalised. Pages are sent concurrently to the gateway with a strict transcription prompt.
  3. Confidence comes from token log-probabilities. A page counts as low-confidence if more than 1% of its words have p < 0.5, any word has p < 0.2, or the model wrote [illegible]. If a second-opinion model is configured, such pages are re-run on it and its output is used.
  4. Hybrid archive. When Paperless asks for a searchable archive PDF, Paperless's own Tesseract/ocrmypdf pipeline builds it, so text positions, PDF/A, deskew and rotation follow your normal OCR settings. The document content (search, AI, matching) comes from the vision model.
  5. Pages the gateway cannot transcribe fall back to local Tesseract, and the document is still consumed.

Which PDFs are OCR'd

Situation Behaviour
PAPERLESS_OCR_MODE=off never OCR'd; embedded text is kept
PAPERLESS_OCR_MODE=redo / force always OCR'd
no real embedded text OCR'd
scan that already has a (scanner) OCR text layer OCR'd again, because pages are full-page images (EXISTING_TEXT=auto)
born-digital PDF (text, no full-page scan images) embedded text kept, no API call

Set PAPERLESS_CF_OCR_EXISTING_TEXT=trust to keep any existing text layer, as Paperless does. Set it to ignore to always OCR.

Results from testing

These are measured on three real documents: a typed letter, an NHS GOS 2 form with handwriting, and a poorly photocopied allergy action plan with handwriting. Scores are the share of key values (names, dates, phone numbers, prescriptions, handwritten notes) transcribed correctly.

Typed letter (word F1) Form + handwriting Degraded copy + handwriting Speed (median / page) Cost / 1,000 pages
Existing scanner OCR (Tesseract) 0.980 24/26 10/21 – –
Qwen 3.8 27B (default) 0.997 26/26 18–19/21 16 s ~$3.50
Mistral Small 3.1 0.996 25/26 18/21 15 s ~$1
Claude Sonnet 5.5 0.998 26/26 21/21 5 s ~$15

Workers AI latency varies a lot under load, with occasional pages taking up to about 100 s. The plugin processes 4 pages at a time.

Requirements

  • Paperless-ngx 3.0.5 or newer. Every 3.x minor release from 3.0.5 to 3.5.1 is tested end-to-end in the official Docker image. Before 3.1 there is no PAPERLESS_REMOTE_OCR_MODE, so the plugin handles every supported document.
  • A Cloudflare account with an AI Gateway. New gateways require authentication.
  • A Cloudflare API token with Workers AI: Read and AI Gateway: Run. With both permissions, this one token also passes an authenticated gateway. A separate gateway token (PAPERLESS_CF_OCR_GATEWAY_TOKEN) is optional.

Privacy. Page images leave your server and are processed by Cloudflare Workers AI. With a third-party second-opinion model such as anthropic/..., they are also processed by that provider. AI Gateway request logging stores the full requests and responses, which means your document images and their text. Disable log collection on the gateway you use for OCR, or restrict logging to metadata.

Installation

A small, versioned installer image copies the plugin into a volume that Paperless loads through PYTHONPATH. It needs no internet access at Paperless startup and no init script, and it works with rootless Paperless containers. Add the parts marked # --- add in deploy/docker/compose.example.yml to your compose file, create cf-ocr.env from deploy/docker/cf-ocr.env.example, then run:

docker compose pull && docker compose up -d
docker compose logs webserver | grep -i "third-party parser"
# Loaded third-party parser 'Cloudflare AI Gateway OCR' v0.1.0 ...

To upgrade or roll back, change the installer image tag.

Docker: install from PyPI at startup

Mount deploy/docker/init/ at /custom-cont-init.d (read-only, owned by root). The script runs pip install paperless-cf-ocr with --no-deps on every container start. It needs root and internet access. Pin the version with PAPERLESS_CF_OCR_VERSION.

Native (bare metal)

Install into the Python environment that runs Paperless, then restart all Paperless services:

sudo -Hu paperless pip3 install --no-deps paperless-cf-ocr

--no-deps is safe because the plugin only imports libraries that Paperless already ships (httpx, Pillow, pypdfium2). Put the settings into paperless.conf.

Configuration

Only a gateway and a credential are required.

Variable Default
PAPERLESS_CF_OCR_ACCOUNT_ID, PAPERLESS_CF_OCR_GATEWAY_ID gateway location…
PAPERLESS_CF_OCR_GATEWAY_URL …or https://gateway.ai.cloudflare.com/v1/<account>/<gateway>
PAPERLESS_CF_OCR_API_TOKEN sent as Authorization: Bearer
PAPERLESS_CF_OCR_GATEWAY_TOKEN sent as cf-aig-authorization (authenticated gateways)
PAPERLESS_CF_OCR_MODEL @cf/qwen/qwen3.8-27b @cf/... models use the Workers AI route; provider/model uses the gateway's OpenAI-compatible route
PAPERLESS_CF_OCR_SECOND_OPINION_MODEL off e.g. anthropic/claude-sonnet-5-5
PAPERLESS_CF_OCR_SECOND_OPINION low-confidence always: send every page to the second model (primary as fallback)
PAPERLESS_CF_OCR_LOW_CONFIDENCE_RATIO 0.01 share of words with p < 0.5 that makes a page low-confidence
PAPERLESS_CF_OCR_LOW_CONFIDENCE_MIN 0.2 any word below this makes a page low-confidence
PAPERLESS_CF_OCR_EXISTING_TEXT auto auto / trust / ignore, see above
PAPERLESS_CF_OCR_ARCHIVE hybrid none: never build archive PDFs (saves Tesseract CPU)
PAPERLESS_CF_OCR_FALLBACK tesseract fail: fail the document when a page cannot be OCR'd
PAPERLESS_CF_OCR_PROMPT / _PROMPT_FILE built-in strict prompt override the transcription instructions
PAPERLESS_CF_OCR_EXTRA_PARAMS {} JSON merged into primary-model requests
PAPERLESS_CF_OCR_TIMEOUT 180 seconds per request
PAPERLESS_CF_OCR_MAX_RETRIES 4 retries on 408/429/5xx, network errors, empty answers
PAPERLESS_CF_OCR_CONCURRENCY 4 pages in flight per document
PAPERLESS_CF_OCR_DPI / _MAX_IMAGE_PX 200 / 2048 page rendering
PAPERLESS_CF_OCR_MAX_PAGES 200 also limited by PAPERLESS_OCR_PAGES
PAPERLESS_CF_OCR_MAX_TOKENS 8192 output limit per page
PAPERLESS_CF_OCR_SCORE 30 parser priority
PAPERLESS_CF_OCR_ENABLED true false disables the plugin without uninstalling it

Reusing Paperless's AI settings

If Paperless's AI backend is openai-like and its endpoint is the gateway's compat or workers-ai route, for example PAPERLESS_AI_LLM_ENDPOINT=https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/compat, the plugin reuses that gateway and API key. Values set in the Paperless UI take precedence over environment variables, as in Paperless itself. Provider routes such as /openai carry that provider's key, so set PAPERLESS_CF_OCR_API_TOKEN in that case. PAPERLESS_CF_OCR_* variables always override reused settings.

Troubleshooting

The plugin logs to paperless.parsing.cf_ocr:

  • Cloudflare OCR configured: gateway=… model=… auth=…: the effective settings, without secrets.
  • page 2: @cf/qwen/qwen3.8-27b confidence mean=0.957 low=2.1% min=0.17 …: the per-page confidence.
  • Cloudflare OCR: 4 page(s), 1 low-confidence, 1 second opinion(s), 0 failed: the per-document summary.
  • HTTP 401 from AI Gateway: check the tokens. Gateways with authentication need PAPERLESS_CF_OCR_GATEWAY_TOKEN or a token with AI Gateway permissions.

If the plugin is not configured, Paperless silently uses its built-in parsers, and the reason is logged as a warning.

Development

python3 -m venv .venv-dev && . .venv-dev/bin/activate
pip install -e '.[dev]'
pytest                                   # unit tests (Paperless is stubbed)

# integration tests against real Paperless parsing code + Tesseract/ocrmypdf
# (needs tesseract, ghostscript, poppler, unpaper):
pip install -c tests_integration/constraints-paperless-3.5.1.txt ocrmypdf pikepdf pillow pypdfium2
tests_integration/fetch_paperless.sh && pytest tests_integration

Run the two suites in separate pytest invocations. tools/lab/ holds the model evaluation tooling used to choose the defaults.

License

GPL-3.0-only, matching Paperless-ngx.

Metadata

Release files for paperless-cf-ocr 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for paperless-cf-ocr 0.1.0
File Size Uploaded Provenance Actions
paperless_cf_ocr-0.1.0.tar.gz 56.6 kB With provenance Details for paperless_cf_ocr-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for paperless-cf-ocr 0.1.0
File Interpreter ABI Platform Actions
paperless_cf_ocr-0.1.0-py3-none-any.whl Python 3 none any Details for paperless_cf_ocr-0.1.0-py3-none-any.whl

Total release size: 93.0 kB

Release files / paperless_cf_ocr-0.1.0.tar.gz

Download URL paperless_cf_ocr-0.1.0.tar.gz
Size 56.6 kB
Tags Source
SHA-256 checksum
How to use checksums
e1b9d1540143e5c671bee808d77dd3416d2d29c7a03f523bf4cb545511fc36c8
BLAKE2b-256 checksum
How to use checksums
fc0dfeec4c8a8bb085759b0d67e61d0ddd84af1274f98f24406cd27f6ccfb271
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / paperless_cf_ocr-0.1.0-py3-none-any.whl

Download URL paperless_cf_ocr-0.1.0-py3-none-any.whl
Size 36.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f4e5951b6de1cb561abd96335839521a523d6eed5c629c63cfd8e81e950ea248
BLAKE2b-256 checksum
How to use checksums
37e4826f81e974e95e031381423eca2ded6d357bb19de01f57da0b9b9364b76d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for paperless-cf-ocr 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for paperless_cf_ocr-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page