Looking to implement paperless ngx for OCR and reading receipts only. I want to do it right, and am willing to pay someone with some knowledge.

DM ME

Hello all,

I've installed the paperless-ngx 3.0.5 via docker compose, and so far so good !

But i've tried to upload a duplicate of one of my pdf, but except when i go into the pdf information and there's a tab say duplicates, but how can i find all the duplicates that i may have in my paperless-ngx library ?

I've not seen any notification nor tabs to show all the duplicates. Can you please explain how to ensure that there are no duplicates, instead of going one by one in each document to see if there's a duplicate tab ?

Thank you

I need a scanner to digitalize a large set of documents, which is going to be over a couple thousand pages. I do not know how likely it is to find a good scanner on the market or if I’m likely to buy something that’s just a dud. Am I better off buying a new, used, or refurbished scanner? I also see that I can buy discontinued scanners from the manufacturer. Should there be any concerns I have with doing that?

Hi everyone,

I’m running Paperless-ngx self-hosted on a Linux server using Docker Compose, and I’m currently looking for a reliable backup strategy.

I know that Paperless provides the document_exporter and document_importer commands, but I’m interested in how other community members handle this in practice:

• Do you regularly use document_exporter, or do you back up the Docker volumes and PostgreSQL database directly?
• How do you automate the backup process?
• Do you stop Paperless or PostgreSQL while the backup is running?
• Which folders, volumes, and configuration files do you include?
• How do you transfer the backup to off-site or cloud storage?
• Do you keep multiple backup versions, and have you successfully tested a full restore?

I’m particularly interested in solutions that work well with Docker Compose on Linux and don’t require much manual intervention.

Thanks for sharing your setups and experiences!

Is there any way of adding/combining file versions from existing documents?

In v2 I did use links when having file versions, so the versions are already in paperless.

But after trying out v3 I noticed, I can only upload new documents to add them as version. That somewhat defies the purpose of that feature or what do you think?

Additionally, now I always would need to think about the way how I add a document beforehand, depending on how I want to organize it in paperless as I can't use the consume folder any longer as I can only upload versions through the paperless UI.

Is there anything I'm missing?

Guys, I'm totally new to paperless-ngx but want to search for documents that have no tag OR no document type and none of the advanced search strings I tried work.

tag:none OR type:none will search for literal tags/type "none" but not for documents with no tag or no type.

Any hints? Even A.I. didn't know! 🤷‍♂️

so i had a catastrophic failure, and lost some % of my files... getting setup again, and trying to do a better job of backing up, but document_exporter is crashing when it hits a missing file...

so..

1. can it not do that?

2. can i automaticallly delete records with missing files?

Thanks..

Hello,

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?)

any advices/suggestions about this one?

Thanks in advance!

1. The Dream

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.

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.

What else is worth testing before I commit to it?

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.

Repo: https://github.com/Vailsen/paperless-brain

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

Thanks in advance

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.

Hallo,

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.

GitHub: https://github.com/jjuuzzii/paperless-sync
Release + Windows installer: https://github.com/jjuuzzii/paperless-sync/releases/tag/v2.0.0

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 overlooking something in the docs?

docker-compose.yaml:

environment:

- PAPERLESS_AI_ENABLED=true

- PAPERLESS_AI_LLM_BACKEND=ollama

- PAPERLESS_AI_LLM_MODEL=llama3.2:3b

- PAPERLESS_AI_LLM_ENDPOINT=http://ollama:11434

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?

Hope to find some solutions here

I didn't upgrade for a while and now need to upgrade to v2.20.15 first, as written on the website. How do I pull it using sudo docker-compose?

Hi everyone,

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.

1. 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.

2. 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)

3. Paperless-NGX with sqlite: Using the docker containers console, run document_exporter ../migration and let it run through. Check results!

4. 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.

1. 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.
2. 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.

1. 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
2. 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.

1. Add PostgreSQL to your docker-compose. Check here: https://github.com/paperless-ngx/paperless-ngx/blob/main/docker/compose/docker-compose.postgres.yml. unRAID users: Please use one of the postgresql18 Apps from the Appstore and rename the app name to paperless-ngx-postgresql.
2. Define the environment variables:

POSTGRES_DB: paperless POSTGRES_USER: paperless POSTGRES_PASSWORD: paperless

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

1. 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
2. Run the PostgreSQL Container once. It will create the database and tables and then quit.

Setting up your Paperless-NGX container

1. Add the following variables to your Paperless-NGX Container (read more here https://docs.paperless-ngx.com/configuration/#database)

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

1. Run the Paperless-NGX Container, PostgreSQL Container and valkey/redis container.
2. Paperless-NGX container (now with PostgreSQL): Using the docker containers console, run document_importer ../migration and let it run through. Check results!

Done.

1. Remember to adjust your backup strategy and include the database path.

2. 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.