paperless-gpt's biggest release in a long time — a ground-up redesign of the web UI, LLM-based OCR promoted to a first-class feature with its own Playground and Activity log, a read-only view of your entire live configuration, and a clear ramp from manual runs to fully hands-off automation.
The theme is clarity: you can finally see what paperless-gpt is doing, tune it with confidence, and trust it to run on its own.
Heads-up: this release moves the OCR route to
/ocrand drops theMANUAL_OCR_TAGqueue in favor of the new Playground + Auto-OCR flow. See Notable changes below.
✨ A redesigned, dark-mode-first web UI
The interface users called the app's weakest point has been rebuilt from the ground up — calm, precise, and trustworthy.
- First-class dark mode (not an inversion): surfaces gain depth through lightness, scans stay crisp, contrast holds everywhere. Follows your system theme, with a manual toggle.
- A consistent design system: OKLCH color tokens, a real type scale, and one shared button/badge/chip vocabulary across every screen.
- The familiar select → generate → review → apply flow is intact — upgraded with clearer diff cards and an optional focus mode — so the ~1M existing installs feel instantly at home.
🔬 OCR Playground & Activity
LLM-based OCR is no longer "experimental" — it's the headline feature, with a workspace to match.
- Playground (
/ocr): pick any document, run OCR, and see the scan beside the recognized (editable) text. Tune per-run options — page limit, process mode, searchable-PDF handling, prompt override — and re-run any past run with adjusted settings. - Compare runs side by side and re-OCR individual pages.
- Activity log (
/ocr?tab=activity): a persisted record of every OCR run, manual and automatic, with status, duration, page counts, and clear warnings when an original was replaced by a searchable PDF.
🤖 A ramp to hands-off Auto-OCR
The Playground exists to build your trust, then get out of the way.
- Dial in options that work, hit Save as defaults, tag documents with your Auto-OCR tag, and paperless-gpt processes them automatically using those defaults.
- The Activity log is your safety net for verifying what ran overnight.
⚙️ Active Configuration view
A new read-only page under Settings shows every setting the running instance is actually using — all 80+ environment variables, what each one means, and where its value comes from (env, saved-in-app, or default). Secrets are shown only as set / not set, never revealed.
- Makes 12-factor config legible: when a saved in-app default shadows an environment variable, the UI says so explicitly (and it's logged at startup).
🐛 Fixes & polish
- Stop endless OCR retries — failed auto-OCR now gives up after
OCR_MAX_RETRIESattempts and applies a fail-tag instead of looping forever. Thanks @lunetics! (#1008) - "Save as defaults" is now a clear, prominent control — the promotion-to-automation action it was always meant to be.
- The Playground now teaches on first open instead of showing an empty canvas.
- Model scaffolding no longer leaks into recognized text — a stray
```markdownwrapper from vision models is stripped at the source, so it never reaches your archive. - OCR failures are diagnosable — full error messages and long document titles are now reachable (keyboard- and screen-reader-friendly), not hidden in a tooltip.
📚 Under the hood
- Docs: contributor instructions migrated to the standard AGENTS.md format.
- OCR runs are now persisted and re-runnable units with per-run options.
🙏 Credits
- @lunetics (Matthias Breddin) — the endless-retry fix (#1008).
- Christian Hessel — the async job-processing foundation this release's flow is built on (#984).
- Everyone who reported that the UI needed love. This one's for you.
Full Changelog: v0.26.1...v0.27.0