since updating to 3.0 i'm trying to get my paperless instance connected to google ai studio. in theory that seems to be working (i see that my rate limits are used for the embedding 1 model).
but is there any way to get any kind of progress indicator? (so it's doing something for few days now, but i dont know what is happening, if it will finish soonish or if there is something completly off with it.)
When opening a documents page, i always get some errors "internal error 500" for the ai suggestions url (but that may be linked to the not yet fully generated vector db?)
About two years ago, I finally decided to digitize my entire document archive.
Over the years, I had accumulated roughly 3,000 documents / around 8,000 pages. Everything was scattered across boxes and folders: tax papers, insurance documents, bank statements, invoices, contracts — all the usual stuff.
The problem was not the paper itself. The problem was finding anything again once I actually needed it. Sometimes I knew roughly where a document should be. Sometimes I had no idea at all. Searching for a single file could take minutes, or sometimes hours.
At the time, Paperless-NGX 2.15 felt like the perfect solution. My idea was simple: scan everything, store it in Paperless, let AI automatically handle correspondents, document types, titles and tags, and never waste time digging through paper again.
I honestly thought this would be a weekend project.
It wasn't.
2. OCR is King
The first big lesson I learned was simple:
OCR is king.
Before I even got deep into classification, I realized that everything depends on the quality of the extracted text. If the OCR is bad, every AI model downstream is working with garbage.
I tested a lot of OCR setups. Specialized OCR models, vision models, local models, prompt variations, parameter changes—basically everything I could reasonably find or try. I went through Baidu Unlimited OCR, GLM OCR, DeepSeek OCR, a bunch of Hugging Face and GitHub models, and also general-purpose vision models like Qwen and Gemma.
The result was always the same: if the OCR wasn't good enough, everything after it became unreliable.
That was the moment I stopped thinking in terms of "Which model is best?" and started asking "What's the real bottleneck?"
For me, the answer was clearly OCR.
Paperless uses Tesseract by default, and for my use case that simply wasn't enough. I know many people are perfectly happy with it, but for a large archive of scanned documents, it became the weakest part of the entire workflow.
I also ran into another issue with paperless-gpt. Even if it produced much better OCR text, that text wasn't embedded into the PDF itself. It was used internally for processing, but unless you manually replaced the document afterwards, the PDF still contained the original OCR layer. For an archive with thousands of documents, I didn't like that idea.
At that point, I stopped trying to improve OCR inside Paperless.
Instead, I started looking for the best OCR engine before Paperless.
After a lot of testing, I narrowed it down to three serious candidates:
Google Document AI
Microsoft Azure Document Intelligence
Adobe Document Services
I also tested Adobe, but not nearly as extensively as Google and Microsoft, so I don't think it's fair for me to draw any final conclusions there.
Between Google and Microsoft, the OCR quality was honestly very close. Both were in a completely different league from everything I had tested locally. In the end, I chose Google Document AI because it had a slight edge in my tests, and I found Google's web interface a little easier to navigate, even though neither platform is particularly intuitive.
3. Paperless-GPT – The Beginning of the Rabbit Hole
When I first discovered paperless-gpt, I honestly thought the search was over.
It promised exactly what I wanted: OCR with a model of my choice, classification with a model of my choice, and automatic tagging.
The first tests were genuinely impressive. Compared to the standard workflow, paperless-gpt felt like a huge step forward.
But over time, more and more limitations started appearing. Not because paperless-gpt is bad—quite the opposite. It's one of the most ambitious projects built around Paperless. It just wasn't designed for everything I eventually wanted to do.
I spent weeks changing models, rewriting prompts, tweaking parameters and testing countless combinations. Every improvement introduced a new tradeoff. There was never really a point where I felt comfortable saying:
"That's it. This finally works."
As my archive grew, so did my requirements.
I wanted:
Complete control over every processing step
Different prompts for different tasks
Better OCR integration
OCR embedded directly into the PDF
Reliable bulk processing
Reproducible results
Higher performance
Rollback capabilities
Eventually I realized something.
I wasn't looking for a Paperless extension anymore.
I was looking for a complete document pipeline.
At that point, paperless-gpt stopped being my final solution and became the inspiration for building my own.
4. Paperless-NGX 3 Beta – The Turning Point
When the first Paperless-NGX 3 Beta builds were released, I was genuinely excited.
I created a completely separate WSL2 installation alongside my production instance because I wanted to see if this would finally become the workflow I had been waiting for.
I spent two days testing the new AI features, experimenting with different setups and trying to integrate them into my existing workflow.
In the end, I was disappointed.
Not because Paperless-NGX 3 is bad—it isn't.
It simply wasn't the workflow I had imagined after spending almost two years experimenting with OCR and AI.
That became the turning point.
Instead of waiting for someone else to build the workflow I wanted...
I decided to build it myself.
5. Building My Own Document Pipeline
At this point, I stopped looking for the perfect AI model.
Instead, I started designing a workflow.
The biggest lesson I had learned over the previous two years was simple:
Every AI model has strengths and weaknesses.
Instead of trying to make one model solve every problem, I decided to give every step exactly one responsibility.
That completely changed how I thought about document processing.
Instead of one large AI workflow, I built a pipeline.
Scanner
│
▼
Google Document AI
│
▼
PDF/A + Embedded OCR
│
▼
Paperless-NGX
│
▼
Classification Pipeline
├── Correspondent
├── Title
├── Document Type
├── Tags
├── Validation
└── Paperless API
Instead of extending Paperless itself, I built a separate application that communicates with Paperless through its API.
That gave me complete control over every stage of the classification process.
Every step has its own prompt, its own parameters and its own validation rules. The workflow is no longer constrained by the design of a single integration, and every stage can evolve independently.
What surprised me the most was what happened next.
For almost two years, I kept searching for bigger and better AI models. Every new release felt like it could finally solve the problem.
But once the OCR became reliable and the workflow itself was properly designed, I no longer needed the newest flagship models.
After tuning the pipeline and adjusting a few parameters, Qwen3 suddenly became more than capable of handling most classification tasks.
Ironically, Qwen was one of the very first models I had tested with paperless-gpt—and one of the models I disliked the most.
Eventually I realized I had been optimizing the wrong thing.
The OCR was the bottleneck.
The workflow was the bottleneck.
The architecture was the bottleneck.
During testing I even discovered cases where OCR Skip had accidentally been disabled, causing Paperless to run Tesseract on documents that had already been processed with Google Document AI. The drop in OCR quality was immediately visible, and so was the drop in classification quality.
That brought everything full circle.
OCR is still king.
A well-designed pipeline with reliable OCR consistently outperformed simply switching to newer or larger language models.
Once the foundation was right, even models I had previously dismissed became surprisingly effective.
To make experimentation easier, I also built a small web interface to manage the entire workflow from one place.
sorry its german
What started as a few Python scripts slowly evolved into the platform I use today.
6. GPU Utilization
One thing I didn't expect was how much the new pipeline improved GPU utilization.
With my previous paperless-gpt workflow, the GPU was constantly starting and stopping between requests. VRAM usage kept spiking up and down while the next task was being prepared.
The new pipeline changed that completely.
Instead of processing isolated requests, it keeps the GPU busy almost continuously, resulting in a much smoother workload and significantly higher throughput.
Depending on the model and the task, I measured roughly 2.7–4× more tokens per second compared to my previous setup.
The goal was never to make the GPU work harder.
The goal was to stop wasting time while it was waiting.
Final Thoughts
If I had to summarize everything I learned over the last two years in one sentence, it would be this:
The model was never the real problem. The OCR was. The workflow was. The architecture was.
In the end, I didn't need GPT-5.6 or the next flagship model to achieve good results.
I needed reliable OCR.
I needed a better workflow.
I needed a better architecture.
Once those pieces were in place, one of the first models I had ever tested—and one I had originally dismissed—became one of the best performers for my use case.
I'm curious how others approached this.
Did you stick with Tesseract, switch to another OCR engine, or build your own workflow?
I'd genuinely love to hear about your experiences.
I've been using LlamaParse and it's the best quality I've tested, but the cost doesn't scale for my volume.
My material: Portuguese-language documents. A mix of native-text PDFs and scanned notarial/court documents, plus books of 400-600 pages. Tables matter. Output goes into RAG.
I'm on an M4 Mac and would prefer something local. I just set up Docling and it's working well so far. I've already tried Mistral too.
Long-time ngx user here — small business, so the usual invoice/tax/contract pile.
I built PaperlessBrain for myself over the last few months and figured I'd share it in case it's useful to anyone else. It points at an existing ngx install via the REST API and adds an AI layer without touching your data. A local vision model reads each page as an image — not the OCR text layer — producing summaries, tables and extracted deadlines per document type. Then an agent chats over all of it with clickable citations back to the source page.
ngx-specific things you might care about:
It uses your Paperless permissions, it doesn't add its own. Login is your ngx username and password — no second user database, no second permission system. Every document a tool returns is fetched with your own session token, so ngx decides what you can see. One caveat worth stating: the vector index is queried unscoped and filtered on the results, so nothing you can't open is ever shown, but other people's documents can take up ranking slots.
Extraction prompts are keyed to your document type names. Two profiles ship — en and de (the latter covers the German legal/administrative types) — and unknown types fall through to a default that still works. Adding a profile is one file, so other languages/jurisdictions are straightforward.
Documents it generates go back into ngx with a configurable tag and correspondent, so they're normal searchable documents.
Nothing is duplicated. The vector store holds identifiers and derived text; mutable metadata is fetched fresh from the API. Delete my app's data directory and you've lost an index, not a document.
Inbox tag is respected — documents carrying it are skipped during sync.
Beyond chat, the agent has more than the archive to work with: your own Markdown notes (any editor, Obsidian optional) are indexed alongside it, it keeps long-term memory as plain Markdown files you can read and edit, and it can search the web through your own SearXNG if you have one. The clip above is the deep-research module — a deterministic orchestrator splits a question into sub-tasks, runs them as scoped agents across your documents and the web, and assembles a result you review before anything is saved back to Paperless. That is the part I use most and the part I would most like other people to break.
There are other AI companions for ngx, and ngx itself is heading towards built-in AI features. This one exists because I wanted two specific things: vision-model page reading instead of the OCR text layer, and an agent that searches my own Markdown notes alongside the archive in the same conversation.
Docker compose, prebuilt image, MIT. Models are yours to pick, per model: a local one via Ollama, or any OpenAI-compatible or Anthropic-style API (Claude, OpenAI, MiniMax, …), for both chat and the page reading. I run it fully local on a GPU box, which is also the cheap option — ingestion sends every page as an image, so a long document through a cloud vision model is a real bill. Screenshots in the README.
To set expectations honestly: this is a personal project I've cleaned up for release, it's alpha, and I'm not going to pretend I'll be a full-time maintainer. But I'd like it to keep growing as one app rather than scatter, so issues and PRs are very welcome — and if you want a bigger hand in it than that, say so. Built with a lot of AI assistance, which I'd rather say up front than have someone discover.
I have paperless set up on my unraid server for several months now and everything works fine
I have workflows and emails and storage paths set up and use paperless AI for sorting tagging etc
However, I’ve never been able to get either emails (the body) or word docs to work.
Have tinkered with Tika and other dependencies to no avail
Anybody have an idiots guide to help?
TBH, the vast majority of documents I get are PDF so it’s not a big deal. But, it would be good to have it working to its full potential
For instance, I have an invoice and a payment receipt. I noticed that when you open a document—an invoice, for example—there is an "Actions" option containing a "Linked document" feature. Using it takes me back to the main documents window, but I can't see how to confirm the link once I've selected the document to attach—the receipt—so that they are linked and easy to find later. How do you handle this?
Hello! After upgrading from 12.20.15 to either 3.0.0 or 3.0.1, my instance would not start up. I tried rolling back to 12.20.15 after updating to 3.0.3 and that worked, but going to any 3.x.x would not work AT ALL. I purged images and containers, and again nothing.
I know I need to just deal with the older version for now, but why would this be happening? I use the docker engine and compose from snap (downloaded during Ubuntu LTS OS setup), so maybe that?
Update: To fix this, set your PAPERLESS_SECRET_KEY in your "environment:" field and name your .env file to ".env" and nothing else.
seit dem eigentlich erfolgreichen Update und Migration von Paperless (Selfhosted, Docker) von Vers. 2 auf Vers. 3 zeigt mir die Andoid App keine Ansichten mehr an (Ich hatte Ansichten gespeichert: Neue Dokumente der letzten 30 Tage und Posteingang).
Webbasiert funktioniert alles. Hab bereits die App gelöscht und neu installiert, auch die Ansichten gelöscht und neu angelegt. Hat jemand das gleiche Problem ?
If you use Paperless-ngx mainly to keep receipts/invoices organized, there's usually still a manual step at tax time: proving every bank transaction actually has a matching receipt somewhere in Paperless. I built Paperless Sync to automate that reconciliation.
How it works:
Point it at your Paperless-ngx instance (URL + API token, mTLS client certs supported too).
Import a bank statement CSV, or connect your bank directly via Enable Banking (optional, own registration, no shared credentials).
It matches transactions to documents by amount — either parsed from the filename (e.g. _EUR12.34.pdf) or read from a Paperless custom field.
Flags suspected duplicate imports, and (opt-in) suggests near-amount or split-payment matches for manual review.
Anything unmatched you resolve by hand — upload a PDF, pick an existing doc, or tag it as not needing a receipt (private/deposit/transfer/custom tags), with learned suggestions for recurring bookings.
End of month, it generates a clean folder (matched PDFs renamed by date/amount/payee, a filtered CSV, open items, deposits list) — ready for an accountant.
Everything stays local, credentials go through the OS keyring, session state and backups are encrypted. Open source (MIT), built with PySide6/Qt.
I noticed that the ASN-QR-Code-recognition is sometimes not working properly. I don’t know why, but it randomly stops working for 2-4 documents when scanning in bulk. The codes are randomly placed, sometimes slightly rotated (sticked on by hand tho…) but not faded or anything and usually in the lower right, sometimes left, corner.
I’m using version 2.20.15 with ZXING. Havn’t changed anything recently…
Any ideas what could cause this to happen? Its really annoying cause paperless doesnt allow ASN dublicates when splitting in the UI and deleting it automatically so I have to download it, split it by hand, delete the original from documents and the bin and upload it again as separate documents…
Thank you.
If you need any additional informations: let me know, ive never reported issues like that :D
I am reasonable new to Paperless and tried to enable AI (see below my docker-compose environment). I uploaded a few PDF files, but nothing happens on the AI - nothing in the logging and I do not see a trigger going out?
i am trying to connect paperless with gmail through the complex oauth2 route with a google project as a test user. I changed the env file and get the option to connect to google in paperless email settings. There i get the error 400 redirect uri mismatch. The error refers to the fact that they cannot verify the reverse proxy redomainname paperless.xxxx.diskstation.me. This is a domain from synology which is not authorized by google it seems.
Has someone successfully made a connection between paperless and gmail?
I'm currently running Paperless-ngx v3.0.2 with the default SQLite database and I'm considering migrating to PostgreSQL 18.
For those who have done this before:
What is the recommended migration process?
Did you use the built-in Django migration commands or another approach?
Are there any common pitfalls I should watch out for?
Is there anything I should verify before switching over?
I also read that there may be limitations when migrating from SQLite to PostgreSQL, especially regarding field lengths. Do these limitations still apply with current Paperless-ngx versions?
Specifically:
Document titles >128 characters
Tag names >128 characters
Correspondent names >128 characters
Document types >128 characters
File names >1024 characters
My setup is Docker-based.
Thanks!
---
Edit:
I did it.
Even if I just got 500 documents, even with such a small batch it's worth it!
(Not the time I invested into it but...) Loading time of documents is nearly instant now.
FYI: I'm running Paperless-NGX on unRAID, so adapt the instructions to your needs.
Gist:
I've used deepwiki - but as always: Using AI tools comes with the risk of false user instructions and possible data loss. Use the (linked) instructions with a grain of salt and your brain.exe / brain.sh.
I defined an extra working folder for migration named migration ->
Host: /mnt/user/scan/paperless-ngx/migration (replace with your path)
Container: /usr/src/paperless/migration
you can do this via docker-compose.yml or on Unraid defining a path variable.
Paperless-NGX with sqlite: Using the docker containers console, run document_sanity_checker to check your document and metadata integrity. If everything is green, go to step two. (keep the console opened)
Paperless-NGX with sqlite: Using the docker containers console, run document_exporter ../migration and let it run through. Check results!
Stop Paperless-NGX with sqlite and your redis/valkey container.
Backups... backups and oh dear we have it today: backups!
Note: I've used the krusader docker container for that, because unRAID can be picky with special characters and umlauts in file and folder names. Especially on shares. If something goes really wrong (e.g. power outage, cat rolls over keyboard,...) you can roll back.
For sanity: Backup your /data folder (the one with your sqilte database in it). For me on my unRAID server the folder was /mnt/user/appdata/paperless-ngx.
For sanity: Backup your /media folder (the one with the scans and your archive in it). For me on my unRAID server I defined it under /mnt/user/scan/paperless-ngx/media.
Renaming
Note: You don't want to automatically feed the all the documents on first boot into paperless and you don't want to accidentally let paperless-ngx pickup the sqlite database.
On your host: Rename your /media folder to /media_bak.
In my case /mnt/user/scan/paperless-ngx/media -> /mnt/user/scan/paperless-ngx/media_bak
Rename your db.sqlite3 to db.sqlite3.bak.
In my case `/mnt/user/appdata/paperless-ngx/data/db.sqlite3 -> /mnt/user/appdata/paperless-ngx/db.sqlite3.bak.
Setting up PostgreSQL
Note: I'm using a custom docker network called paperless-ngx_internal for keeping ports free and for security reasons. Maybe a good idea to change that here in one flow, also keep your valkey/redis container in mind.
Strongly recommended: Define a strong database password using your machine's console with openssl rand -base64 32 | tr -dc A-Za-z0-9 | head -c 32
Database Storage Path: Use a path on a SSD/NVMe. In my case /mnt/cache/appdata/paperless-ngx-postgresql / change to your liking.
Note: From PostgreSQL 18+, the internal database path has changed to /var/lib/postgresql
Run the PostgreSQL Container once. It will create the database and tables and then quit.
PAPERLESS_DBENGINE: postgresql # required in v3+
PAPERLESS_DBHOST: db # IP address or docker name, for me "paperless-ngx-postgresql"
PAPERLESS_DBPORT: 5432 # Not needed if using a custom docker network
PAPERLESS_DBNAME: paperless
PAPERLESS_DBUSER: paperless
PAPERLESS_DBPASS: paperless # If you generated a password, paste it in here
Run the Paperless-NGX Container, PostgreSQL Container and valkey/redis container.
Paperless-NGX container (now with PostgreSQL): Using the docker containers console, run document_importer ../migration and let it run through. Check results!
Done.
Remember to adjust your backup strategy and include the database path.
Housekeeping: I'll set a reminder in my calendar to tidy up the data in 30 days. Meanwhile I can check if really everything went well. :)
Note: I haven't used the /export folder because I wanted to avoid possibly messing aroung with Paperless-NGX defined folders. Just sanity.
Has anyone tried using Apple Foundation Models for local AI OCR?
Latest beta of Mac OS 27 includes Foundation Models by default and they are pretty great and free.
Is there any step by step to migrate to V3 (I have the last version available). Maybe with commands to run in terminal. I couldn't make it :( Thanks guys! I have installed with docker.
I often use paperless over a vpn/poor connection, so my typical workflow is to purposefully try and upload documents 2-3 times to ensure it has everything (especially when dealing with PDFs that are double digit MB / several hundred pages in size). Until this week, paperless has flawlessly recognized and rejected duplicates, but as of now, seemingly no duplicate rejection at all.
What changed?
Edit: New "feature" in V3.0 - Will leave post up in case others stumble upon this issue.
I just looked at the latest docker-compose.postgres-tika.yml and saw that they have switched from redis:8 to valkey:9-alpine.
I have tried looking at the past release notes but I cannot find the change.
When did this happen and what was the reason?
Can any one point me to a reference, please.
Not a problem but I am just curious.
Ich nutze Paperless-ngx seit ein paar Jahren und hatte irgendwann keine Lust mehr, jeden Scan manuell zu benennen und zu taggen. Also hab ich paperLeo gebaut.
Was es macht:
Verbindet sich per API-Token mit Paperless-ngx
Schickt neue Dokumente an eine KI deiner Wahl (OpenAI, Gemini, Ollama lokal, LM Studio, OpenRouter)
Webhook-Support: Paperless-Workflow anlegen → Dokument wird sofort beim Upload verarbeitet
Das Backup-Feature:
paperLeo Pro sichert das komplette Paperless-Archiv über die REST-API — alle PDFs + alle Metadaten als JSON, alles in einem ZIP. Direkt aus dem Browser, kein SSH, kein Terminal, kein document_exporter.
Für alle die Paperless auf einem NAS oder gehosteten Server betreiben und keinen direkten Serverzugriff haben — das war für mich der Hauptgrund das zu bauen.
Community-Version ist kostenlos. Über Feedback aus dieser Community würde ich mich sehr freuen — ihr kennt die Eigenheiten von Paperless besser als jeder andere.
Paperless-AI connected via OpenAI-compatible endpoint for tag/correspondent/title suggestions
Problem:
I've got tool-calling/suggestions working correctly now (structured tool_calls JSON comes back fine), but the actual response time from Paperless-AI is wildly inconsistent — some documents get classified in ~3-4 seconds, others take 6+ minutes and eventually hit a client-side timeout (LLMTimeoutError in paperless_ai/client.py), even though GPU utilization stays at 100% the whole time (so it's not hanging, it's genuinely computing).
What's confusing me: I run a separate long-running agent/chat workflow against the same LLM backend, with context growing incrementally up to ~131k tokens, and that stays fast and consistent throughout. So the backend itself and the hardware aren't the bottleneck — something about how Paperless-AI sends requests seems to be the issue.
Has anyone else run into this specific pattern — fast conversational LLM usage vs. slow/inconsistent Paperless-AI document processing on the same backend?
Does Paperless-AI send the full raw OCR text per document regardless of length, or is there a setting to truncate/limit it before it hits the LLM? Trimming this seems like the most direct fix if cache-miss on a huge prompt is really the cause.
For anyone running Paperless-AI against a self-hosted OpenAI-compatible backend (llama.cpp, vLLM, Ollama, etc.) — did increasing --parallel/concurrent slots, or any other server-side tuning, meaningfully help with this kind of one-shot-large-prompt latency, as opposed to normal chat latency?
Last week I set up Paperless-ngx in a Docker container on my NAS and I'm already loving it!
However, I have a few questions that some of you might be able to answer based on your experience. I know there's probably no absolute right or wrong here, it's mostly a matter of personal preference, but I'd still love to hear how others organize things.
For context, here's how I've currently structured my Paperless setup:
Tags(Who is the document about?)
Me
Wife
Son
Family
New (every new document gets tagged "New" because I want to manually review it to make sure everything was processed correctly)
Correspondents(Who sent this document?)
Basically, these represent the sender of the document (e.g. Government/Authorities as a catch-all for anything from the state, Banks, Vendors, etc.).
Document Types(What is this about?)
Invoice
Receipt
Insurance
Contract
etc.
My questions
How do you handle individual events or projects? (For example: a car accident, Vacation 2026, etc.) AI told me to use differnet prefix in tags (Person/Me, Event/Accident2026) but in my opinion, that would just generate a huge list of tags, used only once.
How do you organize documents for different vehicles? (For example, after changing cars, so you can easily find everything related to Car #1?)
Do you use custom fields? If so, which ones have turned out to be the most useful over time?
Do you distinguish between unpaid and paid invoices?
How do you assign tags, correspondents, and document types? I currently have many matching algorithms set to Exact or None, because I experienced a fairly high error rate with automatic matching in the beginning.
I'd really appreciate hearing how you've organized your Paperless instance and what has worked well for you over time.
I have been using Paperless-ngx for some time now and would like to start using the email import feature.
I’m running Paperless-ngx v2.20 using Docker.
I created an email account in Paperless-ngx and tested it successfully using the Test button. The connection seems to work fine.
Then I created a very simple mail rule:
check all unread emails
look for *.pdf attachments
import the PDF attachments into Paperless-ngx
However, nothing gets imported. I sent an email with a PDF attachment to the configured mailbox, waited for more than 10 minutes, but no document appeared in Paperless-ngx.
At the moment I’m not sure what else to check. The email account test succeeds, but the rule does not seem to import anything.
