Release notes from paperless-gpt

v0.28.0 — The Follow-Through Expansion

2026-09-18T10:09:19Z

Automation you can leave alone. This release is almost entirely about paperless-gpt doing what its logs already claimed it was doing — tags that were computed and then silently dropped, retry loops that never concluded, and settings that quietly had no effect.

The theme is follow-through: if the app says it added a tag, the tag is there; if a document can't be processed, it stops being retried and says so; if you set an option, it reaches the model.

Heads-up — two behaviour changes worth reading before you upgrade. See Notable changes at the bottom.

🏷️ Tags that actually get applied

Five separate defects conspired to make completion tags vanish between the log line and paperless-ngx. Every one of them is fixed.

AUTO_TAG_COMPLETE is applied instead of being dropped. The tag was written to an AddTags field that nothing ever read, so it was computed, logged as "adding", and discarded. A second tag path — taken when no other field changed, which is the likeliest case for an already-tidy document — ignored it too. Thanks @skort-90 for the four-document reproduction and @Denim5660 for the original root-cause analysis. (#1059, closes #1006, #1074)
PDF_OCR_COMPLETE_TAG is created at startup, like FAIL_TAG already was. Without it, the name→ID resolution silently skipped a tag that didn't exist yet — which is why this worked for some people and not others, with nothing in the log to explain the difference. (#1064, closes #854)
Tag names now resolve case-insensitively. The rest of the tag handling already ignored case; the name→ID lookup was the odd one out, so a configured Paperless-GPT-Auto-Complete couldn't find a stored paperless-gpt-auto-complete. Where a database holds several case variants, the original (lowest id) wins deterministically and the ambiguity is logged. Thanks @ivanzud! (#1075)
An added tag now wins a name collision with a removed one. Configuring the completion tag to the same name as the trigger tag used to leave the document with neither. (#1059, closes #458)
paperless-gpt's own tags are never offered to the LLM. FAIL_TAG, AUTO_TAG_COMPLETE and PDF_OCR_COMPLETE_TAG were missing from the exclusion list, so the model suggested them as ordinary document tags. With an OCR→tagging workflow that produced an unbounded loop, re-billing every LLM call on each pass. Thanks @hakehardware and @fr0der1c for reporting it, twice. (#1061, closes #877, #1015)

🔁 Loops that end

Three ways the auto pipeline can fail. Until now, only two of them could stop.

Repeated suggestion failures now break the loop. A permanent LLM error — a prompt that can't fit the context, a model that no longer exists — used to re-bill the same request forever: one report measured ~12,000 rejected requests over seven days. Worse, because the poll fetches a single unordered page of 25, enough stuck documents starved everything behind them (67 documents, with the container still reporting healthy). After AUTO_TAG_MAX_RETRIES attempts the auto tag comes off and FAIL_TAG goes on. Thanks @JoGres-DE for an exceptionally precise report. (#1076, closes #1071)
This should also end the "worker goes permanently silent" reports: the poll loop doubles its backoff on every failing cycle, capped at one hour, so a single permanently failing document kept the whole worker in hour-long sleeps until a container restart. With the document leaving the queue, the cycle succeeds and the backoff resets. (likely #1016)
Ollama requests can no longer hang forever. Both Ollama paths ran on a timeout-less HTTP client, so a single stalled generation blocked the background loop indefinitely — recoverable only by restarting the container. OLLAMA_TIMEOUT_SECONDS (default 300s) bounds it. Thanks @swiception! (#1070)
Note this covers the Ollama paths only — other providers still share an unbounded HTTP client, so #937 stays open.

🧠 Ollama: `OLLAMA_THINK` finally does something

OLLAMA_THINK had no effect at all, in either direction. The underlying library nested think inside the request's options object, where the Ollama server doesn't look for it, and dropped the value entirely when it was false.

On thinking-capable models (Qwen 3 / 3.5, Gemma 3) that meant unconditional reasoning: the model spent its output budget on a reasoning trace and returned results that were glacial or empty — worst exactly where it matters most, on closed-list classification and strict JSON.

The metadata path now uses Ollama's official client, where think is a top-level field. Reasoning levels (low / medium / high) work too. Thanks @lunetics for the diagnosis and the implementation, and @andglaser for the independent report. (#1063, closes #1024, #1056)

The same change brings LLM_TEMPERATURE for the text LLM (closes #1033), plus LLM_MAX_TOKENS and OLLAMA_KEEP_ALIVE. Ollama-only variables now warn instead of being silently inert when another provider is configured, and OLLAMA_HEADERS is treated as a secret so credential-bearing headers stay out of the configuration view.

🔬 OCR

OCR_LIMIT_PAGES=0 means all pages again — an explicit zero was being mistaken for "unset" and silently replaced by the 5-page default. Thanks @CBOSSX! (#1047, closes #1037)
Transient provider errors are retried per page (HTTP 429/5xx, exponential backoff) instead of forfeiting the whole document. Deliberately more patient than the suggestion path: a failed page throws away every page before it. Thanks @MarcvsTvllivs! (#1004)
Uploaded files are deleted from Mistral after OCR. They were being left in Mistral's cloud storage indefinitely — a genuine data-retention problem for a self-hosted document tool, and invisible from the outside. Thanks @lunetics! (#1007)
Oversized page images compress correctly. After stepping quality down to fit a size limit, the last-resort resize re-encoded at a higher quality than it had just settled on, partly undoing the reduction. Thanks @maksyms! (#946)
image_limit and image_min_size are configurable for Mistral OCR — raise the minimum to stop small boxed fields (handwritten form entries) being skipped as images. Thanks @jipe-b! (#1050, closes #1048)

🔌 Using a different AI provider

Five separate requests — issues and pull requests — asked for providers that already shipped, one of them implementing a whole provider branch that did nothing OPENAI_BASE_URL didn't already do. That was a documentation failure on our side, not missing features.

OpenAI-compatible providers is a new guide with copy-pasteable configuration for OpenRouter, LM Studio, vLLM, LiteLLM, llama.cpp and Azure — plus the three things everyone gets wrong (a base URL missing /v1, vendor-specific model names, local servers rejecting an empty API key) and a troubleshooting section mapping the recurring errors to their causes. (#1060, closes #864, #908, #1041)

Anything that documents an "OpenAI-compatible endpoint" works today via LLM_PROVIDER=openai plus OPENAI_BASE_URL. No new release required.

⚙️ New options

Variable	What it does
`AUTO_TAG_MAX_RETRIES`	Give up on a document after N failed suggestion attempts (default `3`, `0` retries forever)
`OLLAMA_TIMEOUT_SECONDS`	Per-request timeout for Ollama (default `300`)
`PRESERVE_EXISTING_METADATA`	Keep a correspondent or document type that is already set, so paperless-ngx' own classifier or a manual correction stays in charge. Thanks @keefar! (#1065, closes #1032)
`CORRESPONDENT_PROMPT_LIMIT`	Cap how many correspondents go into the prompt. On a 13k-document instance with 628 correspondents, the correspondent step went from a >10-minute timeout per document to seconds. Thanks @interruptor! (#1043)
`LLM_TEMPERATURE`, `LLM_MAX_TOKENS`, `OLLAMA_KEEP_ALIVE`	Ollama metadata generation
`MISTRAL_OCR_IMAGE_LIMIT`, `MISTRAL_OCR_IMAGE_MIN_SIZE`	Mistral OCR image extraction

🔒 Privacy & deployment

Document content is no longer logged at info level. Full document text was landing in docker logs and any log shipper. Thanks @mrab54! (#922, closes #921)
Non-root containers start correctly — Kubernetes runAsNonRoot and docker run --user now skip the privilege-drop path instead of failing. Thanks @vistalba! (#1002)

📦 Under the hood

The end-to-end test suite works against paperless-ngx 3.x again (it refuses to start on the documented placeholder secret key, so the container died during init) and is pinned by digest instead of tracking :latest. Extracted from @lunetics' work in #1058. (#1062)
Container images are assembled without a redundant cross-registry copy, which was exhausting Docker Hub pull quota on busy days. (#1068)
Dependencies refreshed, including Node 24 and Alpine 3.24.

⚠️ Notable changes

1. Documents whose suggestions keep failing now leave the queue. Previously they were retried forever. After AUTO_TAG_MAX_RETRIES attempts (default 3) the auto tag is removed and FAIL_TAG applied. If you relied on indefinite retries, set AUTO_TAG_MAX_RETRIES=0. This mirrors what OCR_MAX_RETRIES already did for OCR in v0.27.0.

2. Ollama requests now time out after 300 seconds. Previously they could hang indefinitely. If you run very large models on slow hardware and a legitimate generation exceeds five minutes, raise OLLAMA_TIMEOUT_SECONDS or set it to 0 to restore the old behaviour.

Both defaults were chosen so the failure mode is "this document is marked for review" rather than "the worker is silently wedged".

🙏 Credits

This release came almost entirely from the community — reports, diagnoses and code.

@lunetics (Matthias Breddin) — the OLLAMA_THINK diagnosis and native-client implementation (#1063), the Mistral data-retention fix (#1007), and the E2E fixes that unblocked CI for every open PR (#1062)
@swiception — the Ollama request timeout (#1070)
@ivanzud (Ivan) — case-insensitive tag resolution, including the determinism argument that stopped it being subtly wrong (#1075)
@MarcvsTvllivs — per-page OCR retry with backoff (#1004)
@interruptor — CORRESPONDENT_PROMPT_LIMIT, with measurements (#1043)
@keefar — PRESERVE_EXISTING_METADATA (#1065)
@CBOSSX — the explicit-zero page limit fix (#1047)
@jipe-b — Mistral image parameters (#1050)
@maksyms — the image re-encoding fix (#946)
@vistalba — non-root container support (#1002)
@mrab54 — content logging at debug level (#922)
@JoGres-DE, @skort-90, @Denim5660, @hakehardware, @fr0der1c, @andglaser, @nmeden, @vanderfran, @embdMan, @jacobhausler, @Christoph274 — reports precise enough to fix from, several with the root cause already correctly identified

Full Changelog: v0.27.0...v0.28.0

v0.27.0 — The Clarity Expansion

2026-07-21T10:13:57Z

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 /ocr and drops the MANUAL_OCR_TAG queue 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_RETRIES attempts 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 ```markdown wrapper 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

🛠️ v0.26.1 – Patch Release

2026-07-08T12:48:58Z

🛠️ v0.26.1 – Patch Release

Summary

This patch release fixes a regression introduced in v0.26.0 which prevented the container from starting when PUID/PGID collide with users or groups that already exist in the image — most notably on Unraid, which requires PUID=99/PGID=100 (Alpine ships the group users with GID 100, so the container died with addgroup: gid '100' in use in a restart loop).

What's fixed

🟢 PUID/PGID collisions no longer crash the container: the entrypoint now looks up the requested numeric IDs and reuses pre-existing user/group entries instead of failing. Privileges are dropped with numeric su-exec uid:gid, so exactly the requested IDs apply regardless of which entry they resolve to.
🟢 Unraid works out of the box with PUID=99 / PGID=100.
🟢 HOME is now set after the privilege drop, so configs land in /home/paperless-gpt even when the UID resolves to a pre-existing user (e.g. nobody/65534).
🟢 OpenAI-compatible endpoints without the Azure flag: OPENAI_BASE_URL now works for any OpenAI-compatible service (LM Studio, LiteLLM, vLLM, OpenRouter, …) — no OPENAI_API_TYPE workaround needed.

Also included: internal CI improvements (secret-free PR pipeline with mock E2E, environment-approval gate for real-LLM E2E runs — #992, #993, #994).

How to upgrade

Update your paperless-gpt Docker image/tag to v0.26.1.
No migration steps or config changes are needed.

Thanks

Thank you @DennaGherlyn for the quick report and the Unraid details!

#995: "addgroup: gid '100' in use after update to 0.26.0"

What's Changed

fix(entrypoint): support PUID/PGID that collide with existing users/groups in 227b061
feat: OPENAI_BASE_URL for any OpenAI-compatible endpoint + secret-free mock E2E by @icereed in #993
ci: secret-free PR pipeline + environment-approval gate for real-LLM E2E by @icereed in #994
fix(ci): skip registry logins on pull_request builds by @icereed in #992

Full Changelog: v0.26.0...v0.26.1

v0.26.0 - "The Resilience Expansion"

2026-07-07T09:24:27Z

🚀 paperless-gpt v0.26.0 - "The Resilience Expansion"

The container goes rootless, failed updates stop looping forever, monetary fields finally validate, and Ollama gets thinking-mode and reverse-proxy controls — powered by a huge wave of community contributions!

🌟 Major New Features

🔐 Rootless Container

The Docker container no longer runs as root! On startup it creates a dedicated paperless-gpt user (default 10001:10001), fixes ownership of /app, and drops privileges before launching. Customize with the PUID/PGID environment variables.

⚠️ Upgrade note: if you mount volumes (e.g. prompts/, db/, local hOCR/PDF paths), their ownership will be changed to PUID:PGID on startup. If you need the old behavior, set PUID/PGID to match your host user.
Thanks to @hensing for this security win — and for bundling, rebasing and pre-verifying 16 community PRs in #990 to make this whole release possible! 🙏

🛡️ Graceful Recovery from Rejected Updates

When paperless-ngx rejects an LLM suggestion (e.g. an impossible date like 2023-01-79), paperless-gpt no longer retries the same document forever — which could rack up real LLM costs. Instead it now:

Strips the rejected fields and retries so the valid suggestions still land
Removes the auto tag to break the processing loop
Applies a new FAIL_TAG (default: paperless-gpt-failed, auto-created) so you can find and review affected documents
Thanks to @thu1971dlr for tackling this long-standing pain point!

💰 Monetary Custom Field Normalization

LLM-suggested monetary values like USD1,053.52 or EU-style 1.053,52 are now normalized to the canonical format paperless-ngx expects before the update is sent — no more 400 errors and stuck documents from formatting quirks.
Thanks to @bartigas!

🏷️ Let the LLM Create New Tags

With CREATE_NEW_TAGS: "true", the LLM may suggest tags that don't exist in paperless-ngx yet — they'll be created automatically. Off by default, so existing setups are unaffected.
Contributed by @Copilot in #936.

🦙 More Ollama Control

OLLAMA_THINK: Disable (or force) Ollama's reasoning mode. Essential for thinking-mode models (Qwen 3, Gemma 3 families) on tasks that need strict output formats — with thinking left on, they can burn the whole token budget reasoning and return empty content. Thanks @dertbv!
OLLAMA_HEADERS: Pass arbitrary HTTP headers (e.g. Authorization=Bearer mytoken) to every Ollama request — perfect for Ollama behind an authenticated reverse proxy. Thanks @zebrapurring!

✂️ Content Sanitization Before LLM Calls

Strip scanner watermarks, boilerplate, or sensitive markers from document content before it's sent to the LLM:

REMOVE_FROM_CONTENT: comma-separated literal strings
REMOVE_FROM_CONTENT_REGEX: semicolon-separated regex patterns
Thanks to @BieggerM!

📄 Smarter OCR Prompts

The OCR prompt is now rendered per document and can include the text paperless-ngx already extracted ({{.Content}}, capped at 8,000 chars) — giving vision models a reference to cross-check difficult words and numbers against.
Thanks to @adamflagg!

✅ Auto-Processing Completion Tag

Documents finished by the auto pipeline now get an AUTO_TAG_COMPLETE tag (default: paperless-gpt-auto-complete), making it easy to build follow-up workflows. Set it to an empty string to disable.
Thanks to @cfilipov!

🔽 Select-Type Custom Fields

Custom fields of type select now work correctly: LLM-suggested labels are mapped to the option IDs paperless-ngx expects, with proper XML escaping in the prompt.
Thanks to @SEWADE!

🐛 Bug Fixes & Reliability

whole_pdf mode fixed: a variable-shadowing bug made totalPdfPages always 0, preventing PDF generation in whole_pdf mode — thanks @chasebolt! (#909)
PDF_REPLACE loop fix: tag updates are now skipped for documents that were just replaced, avoiding errors on deleted originals — thanks @chasebolt! (#911)
No more crashes on malformed PDFs: gofpdi panics during OCR PDF assembly are recovered so one bad document can't take down the worker — thanks @SAY-5! (#959)
Correspondents no longer show as "private": the owner field is omitted when creating correspondents so paperless-ngx assigns the request user — thanks @sobrino89! (#955)
Dangling <think> tags cleaned up: OCR reasoning cleanup now handles unclosed think tags — thanks @MilanSchilling! (#915)
Data race fixed: settings.CustomFieldsEnable is now read under lock — thanks @adamflagg! (#928)
Lighter polling: document polling is throttled (5s interval) when the queue is empty — thanks @Ruben-E! (#987)
Version in the footer: the WebUI now shows which version you're running — thanks @Copilot! (#905)
Fresh image builds fixed: bumped the pinned musl-dev package after Alpine GC'd the old version, and made the Docker publish workflow fork-aware — thanks @hensing! (#990)
E2E stability: the Mistral OCR E2E assertion is now robust against OCR model drift (#991)
Docs: docker-compose volume fix by @ce603 (#929) and resource-reservation guidance by @kaindlnetwork (#207)

⚙️ Configuration Highlights

New Environment Variables

# Rootless container
PUID: "10001"                       # User ID to run as (default 10001)
PGID: "10001"                       # Group ID to run as (default 10001)

# Update failure handling
FAIL_TAG: "paperless-gpt-failed"    # Applied when a suggestion is rejected (auto-created)

# Auto-processing
AUTO_TAG_COMPLETE: "paperless-gpt-auto-complete"  # Added when auto-processing finishes ("" to disable)
CREATE_NEW_TAGS: "false"            # Allow the LLM to create brand-new tags

# Ollama
OLLAMA_THINK: "false"               # Disable reasoning mode for thinking-mode models
OLLAMA_HEADERS: "Authorization=Bearer mytoken"  # Headers for reverse-proxy auth

# Content sanitization
REMOVE_FROM_CONTENT: "CONFIDENTIAL,Scanned by XYZ"
REMOVE_FROM_CONTENT_REGEX: "Page \\d+ of \\d+;^Fax:.*$"

⚠️ Behavior Change: Rootless by Default

The container now drops root privileges on startup and chowns /app and mounted app directories to PUID:PGID (default 10001:10001). Most setups need no changes; if your volumes require specific ownership, set PUID/PGID accordingly. All other features are opt-in.

📋 What's Changed

Add version display to WebUI footer by @Copilot in #905
Skip tag update for replaced document when PDF_REPLACE=true by @chasebolt in #911
Fix whole_pdf mode page count mismatch preventing PDF generation by @chasebolt in #909
feat: add CREATE_NEW_TAGS env var by @Copilot in #936
Bundle of 16 small, pre-verified community PRs by @hensing in #990, including:
- Reduce document polling load by @Ruben-E in #987
- OLLAMA_THINK env var by @dertbv in #983
- Normalize monetary custom field values by @bartigas in #978
- Break auto-tag loop on update rejection by @thu1971dlr in #976
- Recover from gofpdi panic on malformed PDFs by @SAY-5 in #959
- Drop owner field from correspondent POST when nil by @sobrino89 in #955
- Resolve select-field label-to-ID mapping for custom fields by @SEWADE in #943
- OLLAMA_HEADERS support by @zebrapurring in #938
- README docker-compose volume fix by @ce603 in #929
- Fix data race on settings.CustomFieldsEnable by @adamflagg in #928
- Per-document OCR prompt rendering by @adamflagg in #925
- Content sanitization for LLM API calls by @BieggerM in #917
- Fix OCR reasoning cleanup for dangling <think> tags by @MilanSchilling in #915
- AUTO_TAG_COMPLETE env var by @cfilipov in #892
- Docker Compose resource-reservation docs by @kaindlnetwork in #207
- Run Docker container as non-root user by @hensing in #722
fix(e2e): make Mistral OCR phrase assertion robust to model drift by @icereed in #991

🎉 New Contributors

A huge welcome to our new contributors — this release is overwhelmingly community-built! 🙌

@chasebolt made their first contribution in #911
@Ruben-E made their first contribution in #987
@dertbv made their first contribution in #983
@bartigas made their first contribution in #978
@thu1971dlr made their first contribution in #976
@SAY-5 made their first contribution in #959
@sobrino89 made their first contribution in #955
@SEWADE made their first contribution in #943
@zebrapurring made their first contribution in #938
@ce603 made their first contribution in #929
@adamflagg made their first contribution in #925
@BieggerM made their first contribution in #917
@MilanSchilling made their first contribution in #915

And a special shout-out to @hensing for assembling, rebasing, conflict-resolving and end-to-end testing the 16-PR community bundle. 💪

Full Changelog: v0.25.1...v0.26.0

Ready to upgrade?

docker pull icereed/paperless-gpt:latest

📚 Check out the README for full documentation on all features!

🛠️ v0.25.1 – Patch Release

2026-02-26T14:50:11Z

🛠️ v0.25.1 – Patch Release

Summary

This patch release fixes a regression introduced in v0.25.0 which caused the UI to enter a reload loop and fail to fetch documents from Paperless when the manual queue tag (e.g., with emoji or spaces, like 🤖 AI-Queue) was used.

What’s fixed

🟢 Unicode/emoji tag filtering now works: Fixes improper query encoding for tags with non-ASCII characters or spaces in tags__name__iexact. Paperless-ngx queries by emoji/spaced tags work as expected.
The UI no longer enters a reload loop when a tag like 🤖 AI-Queue is used as MANUAL_TAG.
No changes to other functionality or settings required.

How to upgrade

Update your paperless-gpt Docker image/tag to v0.25.1.
No migration steps or config changes are needed.

Thanks

Thank you to everyone reporting and helping debug this regression!

#898: “400 from paperless-gpt when querying documents by emoji tag via tags__name__iexact” – @icereed

What's Changed

Update README.md by @nettnikl in #895
Fix URL encoding for tag queries with special characters by @Copilot in #901

New Contributors

@nettnikl made their first contribution in #895

Full Changelog: v0.25.0...v0.25.1

v0.25.0 - "The Vision Expansion"

2026-02-16T08:31:48Z

🚀 paperless-gpt v0.25.0 - "The Vision Expansion"

Gemini joins the vision OCR party, polling gets smarter, and image processing becomes fully tunable!

🌟 Major New Features

👁️ Google Gemini as Vision (OCR) Provider

Google Gemini can now be used directly as a vision LLM provider for OCR! With native PDF handling, Gemini supports image, pdf, and whole_pdf processing modes out of the box—giving you even more flexibility for document processing.

Set VISION_LLM_PROVIDER: "googleai" and VISION_LLM_MODEL: "gemini-2.5-flash" to get started
Optional thinking budget support for reasoning models via GOOGLEAI_THINKING_BUDGET
Thanks to @its-a-unixsystem for this fantastic contribution!

🎛️ Configurable Image Processing Limits

Image processing limits are no longer hardcoded! You can now fine-tune max pixel dimensions, total pixels, render DPI, and max file size via environment variables. This is especially useful for smaller vision models like minicpm-v that perform better with appropriately sized images.

IMAGE_MAX_PIXEL_DIMENSION, IMAGE_MAX_TOTAL_PIXELS, IMAGE_MAX_RENDER_DPI, IMAGE_MAX_FILE_BYTES
Sensible defaults maintained for backward compatibility
Great addition by @cfilipov!

⚡ Performance Improvements

🔄 Smarter Paperless Polling

Polling for new documents is now significantly faster and lighter on resources. Instead of querying the full documents API, paperless-gpt now uses tag-based document counting to short-circuit when there's nothing to process—reducing response times from 500–1000ms down to 10–50ms on larger instances.

Fixes high CPU usage on paperless-ngx caused by aggressive polling
Single-tag retrieval replaces multi-tag queries
API calls are aborted early when no documents need processing
Thanks to @apoapoapo for this performance win!

🔧 CI/CD Improvements

🛡️ Secure Fork PR E2E Testing

Fork pull requests can now run E2E tests securely via a label-based approval workflow. Maintainers add the safe-to-test label after code review, which triggers E2E tests with secret access using local Docker builds—no registry credentials needed.
Contributed by @Copilot!

⚙️ Configuration Highlights

New Environment Variables

# Gemini Vision OCR
VISION_LLM_PROVIDER: "googleai"
VISION_LLM_MODEL: "gemini-2.5-flash"
GOOGLEAI_API_KEY: "your-api-key"
GOOGLEAI_THINKING_BUDGET: "16384"  # Optional
OCR_PROCESS_MODE: "whole_pdf"      # image, pdf, or whole_pdf

# Image Processing Limits
IMAGE_MAX_PIXEL_DIMENSION: "10000"
IMAGE_MAX_TOTAL_PIXELS: "40000000"
IMAGE_MAX_RENDER_DPI: "300"
IMAGE_MAX_FILE_BYTES: "10485760"

No Breaking Changes

Existing configurations continue to work as expected. All new features are opt-in!

📋 What's Changed

Add secure fork PR E2E testing with label-based approval by @Copilot in #857
Improve paperless polling for new documents by @apoapoapo in #889
feat: make image processing limits configurable by @cfilipov in #883
add Gemini as Vision (OCR) provider by @its-a-unixsystem in #881

🎉 New Contributors

A huge welcome to our new contributors! 🙌

@apoapoapo made their first contribution in #889
@cfilipov made their first contribution in #883
@its-a-unixsystem made their first contribution in #881

Full Changelog: v0.24.0...v0.25.0

Ready to upgrade?

docker pull icereed/paperless-gpt:latest

📚 Check out the README for full documentation on all features!

v0.24.0- "The Intelligence Expansion"

2026-01-14T21:28:09Z

🚀 paperless-gpt v0.24.0 - "The Intelligence Expansion"

Your AI-powered document processing just got smarter with Claude support, automatic document types, and a whole lot more!

🌟 Major New Features

🧠 Anthropic Claude API Support

Claude joins the party! You can now use Anthropic's powerful Claude models as your LLM provider. Perfect for users who prefer Claude's reasoning capabilities or want an alternative to OpenAI/Ollama.

Set LLM_PROVIDER: "anthropic" and configure your ANTHROPIC_API_KEY to get started
*Thanks to @kamcnally for this excellent addition! *

📁 Automatic Document Type Assignment

Paperless-gpt now intelligently suggests and assigns document types to your documents! Let the AI categorize your invoices, contracts, receipts, and more without lifting a finger.

UI toggle to enable/disable document type generation
View and edit suggested document types per document
Set AUTO_GENERATE_DOCUMENT_TYPE: "true" to get started
Brilliant contribution from @niklasfink!

🎨 Enhanced OCR UI & LLM Options

The OCR interface got a major facelift with more options for fine-tuning your LLM interactions—giving you greater control over how documents are processed.
Improved by @dawidkulpa!

🔧 Improvements & Fixes

🔗 Sub-Path Hosting Support

Hosting paperless-gpt behind a reverse proxy under a sub-path (e.g., /ai/) now works seamlessly! All frontend API calls are now sub-path aware, ensuring the Settings menu and other UI features load correctly.
*Thanks to @tldev-de! *

🐛 OCR Tag Loop Fix

Fixed a critical bug where the auto OCR tag would never be cleared when it was the last remaining tag, causing an endless processing loop.
*Fixed by @haigcd — closes #817! *

🏷️ Tag Removal Fix

Fixed handling of auto/manual tag removal to prevent sending empty arrays, which could cause issues with paperless-ngx.
Fixed by @itkevin — closes #659!

🤖 Reasoning Model Cleanup

OCR output now automatically strips <think> reasoning tags from models like DeepSeek-R1, giving you cleaner extracted text.
*Contributed by @Copilot! *

📄 Docling Provider Enhancements

Updated Docling server API to v1
Added support for PDF processing modes (pdf and whole_pdf)
New environment variables for additional configuration
Thanks to @T-Eberle and @Schweinhitti!

📦 What's Under the Hood

This release includes 100+ dependency updates across both Go backend and TypeScript frontend, keeping everything secure and up-to-date:

Component	Version
React	19.2.3
Go	1.25.5
Vite	7.3.0
Node.js	24
PostgreSQL	18
Alpine	3.23.0
Gin	1.11.0
GORM	1.31.1
LangChainGo	0.1.14
Google GenAI	1.39.0

CI/CD Improvements

Updated to actions/checkout v6, actions/setup-node v6, actions/setup-go v6
GitHub artifact actions updated to latest major versions
actions/cache updated to v5

📋 What's Changed

✨ Features

🔬 Ad-hoc Analysis to get answers from multiple documents by @icereed in #663
🤖 Add Anthropic/Claude API as LLM provider by @kamcnally in #795
📁 Document Type Assignment for Documents by @niklasfink in #848
🎨 Improves OCR UI and adds more options for LLMs by @dawidkulpa in #573

🐛 Bug Fixes

Fix frontend API/base paths when hosting under sub-path (e.g. /ai/) by @tldev-de in #844
Handle situation when auto OCR tag is the last remaining tag by @haigcd in #852
Handle removal of auto/manual tags without sending empty array by @itkevin in #738
Strip <think> reasoning tags from OCR output by @Copilot in #709

🔧 Improvements

Fixed Docling serve API version to v1 & added environment variables by @T-Eberle in #614
Update Docling provider to support PDF processing modes by @Schweinhitti in #758

🎉 New Contributors

A huge welcome to our new contributors! 🙌

@dawidkulpa made their first contribution in #573
@T-Eberle made their first contribution in #614
@Schweinhitti made their first contribution in #758
@itkevin made their first contribution in #738
@tldev-de made their first contribution in #844
@kamcnally made their first contribution in #795
@haigcd made their first contribution in #852
@niklasfink made their first contribution in #848

⚙️ Configuration Highlights

New Environment Variables

# Anthropic Claude Support
LLM_PROVIDER: "anthropic"
ANTHROPIC_API_KEY: "your-api-key"

# Document Type Generation
AUTO_GENERATE_DOCUMENT_TYPE: "true"

No Breaking Changes

Existing configurations continue to work as expected. All new features are opt-in!

Full Changelog: v0.23.0...v0.24.0

Ready to upgrade?

docker pull icereed/paperless-gpt:latest

📚 Check out the README for full documentation on all features!

"The Power User Edition"

2025-09-17T10:15:51Z

🚀 paperless-gpt v0.23.0 - "The Power User Edition"

Bringing AI-powered document processing to the next level with custom fields, external prompts, and enhanced developer experience!

🌟 Major New Features

📝 External Prompts & UI Editor

Transform how you customize AI behavior! You can now manage your prompts externally and edit them through a beautiful web interface. No more diving into config files - craft your perfect document processing prompts with ease.
Thanks to @hensing for this game-changing feature!

🎯 Automatic Custom Field Detection

paperless-gpt now intelligently detects and extracts custom fields from your documents automatically. Let AI discover the data patterns in your paperwork and suggest custom fields you never knew you needed.
Another brilliant contribution from @hensing!

⏱️ Document Processing Runtime Logging

Ever wondered how long each document takes to process? Now you'll know! Every document processing operation is timed and logged, giving you insights into performance and helping you optimize your AI workflows.
Big thanks to @matgoebl for this useful addition!

🛠️ Enhanced Developer Experience

We've added comprehensive GitHub Copilot instructions to make contributing to paperless-gpt a breeze. Whether you're fixing bugs or adding features, the development workflow is now smoother than ever.
Powered by @Copilot's first contribution to the project!

🔧 Infrastructure Improvements

Optional Docker Hub Pushes: More flexible CI/CD pipeline management
Date Validation: Better handling of invalid document dates
Dependency Fortress: Massive dependency update sweep keeping everything secure and up-to-date

📦 What's Under the Hood

This release includes 50+ dependency updates across both Go backend and TypeScript frontend, ensuring you're running on the latest and greatest packages. From React 19.1.1 to Go 1.25.0, we've got you covered.

🎉 New Contributors Welcome!

Special shoutout to @Copilot for joining our contributor family! 🤖

Ready to supercharge your document processing?

📥 Download: Release v0.23.0
📚 Documentation: Check out our updated docs for the new features
🐛 Issues: Found something? We love feedback!

Full Changelog: v0.22.0...v0.23.0

Support relative URLs for reverse-proxies

2025-07-17T08:50:21Z

Support relative URLs for reverse-proxies

Use relative URLs, so forwarding a sub-path from a reverse proxy works. Thanks to @matgoebl.

What's Changed

doc: clarify LLM_LANGUAGE by @thiswillbeyourgithub in #472
chore(deps): update dependency go to v1.24.4 by @renovate[bot] in #465
chore(deps): update dependency @types/react to v19.1.8 by @renovate[bot] in #462
fix(deps): update module google.golang.org/api to v0.239.0 by @renovate[bot] in #444
chore(deps): update dependency postcss to v8.5.6 by @renovate[bot] in #443
chore(deps): update docker.io/golang docker tag to v1.24.4 by @renovate[bot] in #481
fix(deps): update dependency react-router-dom to v7.6.3 by @renovate[bot] in #482
fix(deps): update module github.com/gen2brain/go-fitz to v1.24.15 by @renovate[bot] in #483
chore(deps): update dependency @types/node to v22.15.34 by @renovate[bot] in #430
chore(deps): update dependency typescript-eslint to v8.35.0 by @renovate[bot] in #431
chore(deps): update docker.io/alpine docker tag to v3.22.0 by @renovate[bot] in #447
fix(deps): update module github.com/hashicorp/go-retryablehttp to v0.7.8 by @renovate[bot] in #484
fix(deps): update module gorm.io/gorm to v1.30.0 by @renovate[bot] in #426
chore(deps): update dependency @playwright/test to v1.53.1 by @renovate[bot] in #485
chore(deps): update dependency dotenv to v16.6.1 by @renovate[bot] in #486
chore(config): migrate renovate config by @renovate[bot] in #487
fix(deps): update dependency axios to v1.10.0 by @renovate[bot] in #489
chore(deps): update eslint monorepo to v9.30.0 by @renovate[bot] in #488
chore(deps): update dependency dotenv to v17 by @renovate[bot] in #494
fix(deps): update module google.golang.org/genai to v1.13.0 by @renovate[bot] in #492
fix(deps): update dependency react-tooltip to v5.29.1 by @renovate[bot] in #490
chore(deps): update dependency vite to v7 by @renovate[bot] in #495
fix(deps): update module gorm.io/driver/sqlite to v1.6.0 by @renovate[bot] in #493
chore(deps): update dependency dotenv to v17.0.1 by @renovate[bot] in #499
chore(deps): update dependency @playwright/test to v1.53.2 by @renovate[bot] in #498
fix(deps): update module google.golang.org/api to v0.240.0 by @renovate[bot] in #491
chore(deps): update dependency typescript-eslint to v8.35.1 by @renovate[bot] in #500
chore(deps): update dependency vite to v7.0.2 by @renovate[bot] in #501
chore(deps): update dependency vite to v7.0.4 by @renovate[bot] in #504
chore(deps): update dependency go to v1.24.5 by @renovate[bot] in #503
chore(deps): update eslint monorepo to v9.30.1 by @renovate[bot] in #506
chore(deps): update docker.io/golang docker tag to v1.24.5 by @renovate[bot] in #505
chore(deps): update dependency @playwright/test to v1.54.1 by @renovate[bot] in #507
chore(deps): update dependency @types/node to v22.16.3 by @renovate[bot] in #508
chore(deps): update dependency dotenv to v17.2.0 by @renovate[bot] in #509
chore(deps): update dependency globals to v16.3.0 by @renovate[bot] in #510
chore(deps): update dependency typescript-eslint to v8.36.0 by @renovate[bot] in #511
chore(deps): update eslint monorepo to v9.31.0 by @renovate[bot] in #512
fix(deps): update module golang.org/x/sync to v0.16.0 by @renovate[bot] in #513
fix(deps): update module google.golang.org/api to v0.241.0 by @renovate[bot] in #514
fix(deps): update module google.golang.org/genai to v1.15.0 by @renovate[bot] in #515
chore(deps): update dependency @types/node to v22.16.4 by @renovate[bot] in #517
chore(deps): update docker.io/alpine docker tag to v3.22.1 by @renovate[bot] in #518
Use relative URLs, so forwarding a sub-path from a reverse proxy works. by @matgoebl in #516
chore(deps): update dependency typescript-eslint to v8.37.0 by @renovate[bot] in #519
fix(deps): update dependency react-router-dom to v7.7.0 by @renovate[bot] in #521
fix(deps): update module google.golang.org/api to v0.242.0 by @renovate[bot] in #522
chore(deps): update dependency vite to v7.0.5 by @renovate[bot] in #523
fix(deps): update module google.golang.org/genai to v1.16.0 by @renovate[bot] in #524

New Contributors

@matgoebl made their first contribution in #516

Full Changelog: v0.21.0...v0.22.0

v0.21.0

2025-06-19T14:24:07Z

Release Highlights 🚀

New Features

🔮 Mistral OCR Integration with Advanced PDF Processing

Extended PDF processing support - Mistral OCR now joins Google Document AI in supporting all processing modes: image, pdf, and whole_pdf
Cost-effective OCR - Purpose-built OCR endpoint optimized for document processing with competitive pricing
Markdown-formatted output - Returns well-structured markdown text that preserves document formatting and layout
Large document support - Handles files up to 50MB and 1,000 pages efficiently
Set OCR_PROVIDER: "mistral_ocr" and configure your Mistral API key to get started

🏷️ Enhanced Title Generation with Context

Original title context - Title generation now includes the existing document title as contextual information
Improved relevance - Language models can use the original title to generate more accurate and contextually appropriate suggestions
Better continuity - Maintains document naming consistency while enhancing title quality
Smart fallbacks - Handles cases where original titles are missing or incomplete

Improvements & Refinements

🛡️ Configuration Validation

OCR provider compatibility checks - Prevents invalid combinations of OCR providers and processing modes
Clear error messages - Detailed feedback when unsupported mode combinations are detected
Startup validation - Early detection of configuration issues before processing begins
Provider-specific guidance - Helpful error messages explain which modes are supported by each provider

📄 Enhanced PDF Processing Architecture

Hybrid file naming - Improved PDF splitting with standardized naming conventions that maintain backward compatibility
More provider choice - Users can now choose between Google Document AI and Mistral OCR for advanced PDF processing
Consistent behavior - Both advanced providers support pdf and whole_pdf modes with similar performance characteristics

🧪 Comprehensive E2E Testing

Mistral OCR test suite - Full end-to-end testing of Mistral OCR integration with real PDF documents
Processing mode validation - Tests verify whole_pdf mode works correctly with multi-page documents
Performance metrics - Test output includes detailed comparison of original vs. enhanced OCR content
Cross-provider compatibility - Tests ensure consistent behavior across different OCR providers

Documentation Updates

📚 OCR Provider Comparison

Updated provider documentation - Clear explanation of which providers support which processing modes
Mode compatibility matrix - Easy reference for choosing the right provider and mode combination
Mistral-specific guidance - Detailed setup instructions and best practices for Mistral OCR
Configuration examples - Complete docker-compose examples for all supported configurations

Technical Details

Provider Mode Support Matrix

Provider	image	pdf	whole_pdf
LLM (OpenAI/Ollama)	✅	❌	❌
Azure Document Intelligence	✅	❌	❌
Google Document AI	✅	✅	✅
Mistral OCR (New!)	✅	✅	✅
Docling	✅	❌	❌

What's Changed

feat: Add Mistral OCR provider with advanced PDF processing support - Extends pdf and whole_pdf mode support to a second provider
feat: Add OCR provider and processing mode validation - Prevents misconfigurations and provides helpful error messages
feat: Pass original document title to title generation prompt - Improves context and relevance of AI-generated titles #453
feat: Implement hybrid PDF naming strategy - Improved file naming with backward compatibility
test: Add comprehensive Mistral OCR E2E tests - Full test coverage including diff comparison utilities
docs: Update OCR processing modes documentation - Clear provider compatibility information

Configuration Example

environment:
  # Mistral OCR (new advanced PDF support)
  OCR_PROVIDER: "mistral_ocr"
  MISTRAL_API_KEY: "your_mistral_api_key"
  MISTRAL_MODEL: "mistral-ocr-latest"  # Optional
  OCR_PROCESS_MODE: "whole_pdf"        # Now supported!

Migration Notes

No breaking changes - Existing configurations continue to work as expected
More provider choice - Users now have two options for advanced PDF processing (pdf and whole_pdf modes)

Performance Benefits

Provider flexibility - Choose between Google Document AI and Mistral OCR based on your needs and pricing preferences
Reduced API calls - whole_pdf mode processes entire documents in one request (now available with both advanced providers)
Better accuracy - Direct PDF processing maintains document structure and formatting
Smarter title generation - Original title context leads to more relevant AI suggestions

PRs

fix(deps): update module github.com/pdfcpu/pdfcpu to v0.11.0 by @renovate in #434
fix: mislabeled data types in azure types by @moarsmokes in #455
chore(deps): update react monorepo to v19.1.7 by @renovate in #429
chore(deps): update dependency @vitejs/plugin-react-swc to v3.10.2 by @renovate in #424
Enhance title suggestions with original title by @icereed in #466
[mistral-ocr] Add MIME type detection, structured logging, and improv… by @icereed in #468

Full Changelog: v0.20.0...v0.21.0

Release notes from paperless-gpt

v0.28.0 — The Follow-Through Expansion

🏷️ Tags that actually get applied

🔁 Loops that end

🧠 Ollama: OLLAMA_THINK finally does something

🔬 OCR

🔌 Using a different AI provider

⚙️ New options

🔒 Privacy & deployment

📦 Under the hood

⚠️ Notable changes

🙏 Credits

v0.27.0 — The Clarity Expansion

✨ A redesigned, dark-mode-first web UI

🔬 OCR Playground & Activity

🤖 A ramp to hands-off Auto-OCR

⚙️ Active Configuration view

🐛 Fixes & polish

📚 Under the hood

🙏 Credits

🛠️ v0.26.1 – Patch Release

🛠️ v0.26.1 – Patch Release

Summary

What's fixed

How to upgrade

Thanks

What's Changed

v0.26.0 - "The Resilience Expansion"

🚀 paperless-gpt v0.26.0 - "The Resilience Expansion"

🌟 Major New Features

🔐 Rootless Container

🛡️ Graceful Recovery from Rejected Updates

💰 Monetary Custom Field Normalization

🏷️ Let the LLM Create New Tags

🦙 More Ollama Control

✂️ Content Sanitization Before LLM Calls

📄 Smarter OCR Prompts

✅ Auto-Processing Completion Tag

🔽 Select-Type Custom Fields

🐛 Bug Fixes & Reliability

⚙️ Configuration Highlights

New Environment Variables

⚠️ Behavior Change: Rootless by Default

📋 What's Changed

🎉 New Contributors

🛠️ v0.25.1 – Patch Release

🛠️ v0.25.1 – Patch Release

Summary

What’s fixed

How to upgrade

Thanks

What's Changed

New Contributors

v0.25.0 - "The Vision Expansion"

🚀 paperless-gpt v0.25.0 - "The Vision Expansion"

🌟 Major New Features

👁️ Google Gemini as Vision (OCR) Provider

🎛️ Configurable Image Processing Limits

⚡ Performance Improvements

🔄 Smarter Paperless Polling

🔧 CI/CD Improvements

🛡️ Secure Fork PR E2E Testing

⚙️ Configuration Highlights

New Environment Variables

No Breaking Changes

📋 What's Changed

🎉 New Contributors

v0.24.0- "The Intelligence Expansion"

🚀 paperless-gpt v0.24.0 - "The Intelligence Expansion"

🌟 Major New Features

🧠 Anthropic Claude API Support

📁 Automatic Document Type Assignment

🎨 Enhanced OCR UI & LLM Options

🔧 Improvements & Fixes

🔗 Sub-Path Hosting Support

🐛 OCR Tag Loop Fix

🏷️ Tag Removal Fix

🤖 Reasoning Model Cleanup

📄 Docling Provider Enhancements

📦 What's Under the Hood

🧠 Ollama: `OLLAMA_THINK` finally does something