paperless-gpt: AI OCR and Metadata Tagging for paperless-ngx

What paperless-gpt Solves

paperless-ngx is a popular document management system that handles storage, tagging, and search, but it relies on traditional OCR for text extraction. Traditional OCR often fails on messy scans, handwritten notes, or low-quality images, leaving documents unsearchable. paperless-gpt, written in Go, pairs with paperless-ngx to replace or supplement that OCR with large language models. It also generates document titles, tags, correspondents, and custom fields automatically. The intended user is someone who already uses paperless-ngx and wants to reduce manual sorting time while improving text extraction accuracy. The README claims it saves hours of manual sorting and highlights LLM-enhanced OCR as a key differentiator. This is not a standalone document management system; it is a companion that requires paperless-ngx to function.

How It Works: OCR Providers and Processing Modes

paperless-gpt does not perform OCR itself. Instead, it delegates to one of several providers: LLM-based OCR using OpenAI or Ollama, Google Document AI, Azure Document Intelligence, or a self-hosted Docling Server. The default is LLM-based OCR, which sends images to a vision-capable model for text extraction. The README notes that reasoning models in Ollama, such as qwen3:8b, can improve accuracy, which suggests the tool can use models that think through the extraction task. There are three processing modes. Image mode, the default, processes each page image separately. PDF mode processes PDFs page by page, and Whole PDF mode sends an entire PDF to the provider in one go. Provider compatibility varies by mode, so not every provider supports every mode. The tool also detects existing OCR text to avoid reprocessing documents that already have a text layer. This architecture means the quality of output depends heavily on the chosen provider and model, and the cost can vary widely.

The Web UI and Metadata Generation Pipeline

paperless-gpt provides a unified web UI that shows AI-generated suggestions for titles, tags, correspondents, and custom fields. Users can approve or tweak these suggestions before they are applied to the document. This manual review step is a design choice that acknowledges the imperfect nature of AI output. The UI also offers an auto-processing mode where only edge cases require attention, but the README does not define what counts as an edge case. Custom field generation must be explicitly enabled in settings, and at least one custom field must be selected. Three write modes exist: Append only adds new fields, Update adds and overwrites, and Replace deletes all existing custom fields before writing. Append is described as the safest option because it never overwrites an existing field, even an empty one. This granularity gives users control but adds configuration complexity.

Getting It Running: Docker Compose and Environment Variables

The README states that deployment is simple: a few environment variables and you can run it alongside paperless-ngx with Docker Compose. No sample compose file is provided in the excerpt, but the manual setup section suggests you can also run it without Docker. The project is available on Docker Hub and GitHub Container Registry. Configuration is done via environment variables, though the excerpt does not list specific variable names. Custom prompt templates can be managed through the web UI under Settings. The application uses a safe structure with default_prompts and prompts directories, meaning your customizations persist across updates. To get started, you would need to set up an OCR provider, configure paperless-ngx connection details, and adjust prompts to your document types. The lack of concrete variable names in the material means a new user must consult the full README or repository documentation for exact setup steps.

PDF Text Layer Generation and Its Limitations

One notable feature is the generation of searchable and selectable PDFs. paperless-gpt creates PDFs with transparent text layers positioned accurately over each word, preserving the original appearance. This is a significant improvement over simple OCR text dumps because it makes the document itself searchable. The README lists a section on metadata copying limitations, but the excerpt cuts off before detailing them. That absence is a red flag: if metadata is not preserved when uploading the processed PDF back to paperless-ngx, you could lose custom fields or tags. The safety features section also remains unspecified in the excerpt. Users should verify these limitations before enabling PDF upload to paperless-ngx. The tool offers options to save processed PDFs locally or upload them, but the upload path is where metadata loss could occur.

Costs, Privacy, and Where It Is the Wrong Tool

paperless-gpt is not free to run if you use cloud providers. OpenAI, Google Document AI, and Azure Document Intelligence all charge per page or per token. The README promotes Ollama as a privacy-friendly alternative, but running a local model requires a reasonably powerful GPU or NPU. A small model like qwen3:8b may be a tradeoff between privacy and performance, but the README admits that bigger models enhance the experience if you have enough hardware. For low-volume users, the overhead of running an extra service and reviewing AI suggestions might exceed the time saved. For users with clean, typed documents that traditional OCR handles well, the LLM layer adds cost and latency without clear benefit. Also, if you do not need automated metadata generation, a simpler OCR tool might suffice. The tool is wrong for anyone who expects a fully automatic pipeline without human oversight, because the design includes a review UI for a reason.

Alternatives and the Maintenance Question

The natural alternative is paperless-ngx's built-in OCR, which is free and local, using tools like Tesseract. The difference in approach is that traditional OCR is rules-based and does not understand context, while paperless-gpt uses LLMs that can infer meaning, which helps with messy scans but introduces model dependency. Another alternative is a dedicated OCR service like Google Document AI, but that requires API setup and per-page costs. paperless-gpt actually supports Google Document AI as a provider, so the comparison is not mutually exclusive. For maintenance, the project is under active development, with recent releases including v0.27.0 in July 2026 and patch releases before that. The README mentions a safe prompts directory structure, which suggests upgrades do not overwrite user customizations. However, the project relies on external AI providers that can change their APIs, and the tool must track those changes. The MIT license allows free use and modification, but you must maintain your own instance and monitor for updates.

Editorial conclusion

Adopt paperless-gpt if you run paperless-ngx and need to handle low-quality scans or automate metadata generation, especially if you value local processing via Ollama. Do not adopt it if you expect a fully hands-off solution without verifying outputs, or if you cannot manage extra Docker services and API costs. Verify first that your paperless-ngx version is compatible, that your chosen OCR provider supports your document types, and that you understand the metadata copying limitations before enabling PDF upload. The tool offers a concrete path to better OCR and metadata, but it demands careful configuration and a human review step.

Official sources

1. icereed/paperless-gpt on GitHub
2. Issues
3. License: MIT
4. README
5. Releases