Docspell: Turn Scanned Paperwork into a Searchable Archive

Docspell: Turn Scanned Paperwork into a Searchable Archive

Every small office has a box of paper nobody wants to open. Invoices, contracts, insurance letters, the warranty for the coffee machine. When someone finally needs one, it takes twenty minutes and a bad mood to find it.

Docspell is an open-source document organizer built for exactly that box. You scan or forward your documents, it reads them, suggests who they're from and what they're about, and makes everything searchable. Here's what it does well, what to know before you pick it, and how to get it running.

What Docspell Does

The Docspell docs describe it as a way to keep documents in "a big pile" with good metadata, rather than in a folder tree you have to maintain. In practice:

  • It reads everything. Scanned PDFs and photos go through OCR with Tesseract, office files are converted to PDF, and the text becomes searchable.
  • It suggests the boring metadata. Docspell proposes the correspondent, the people or things a document concerns, dates, due dates and tags. It learns from documents you've already filed, so suggestions get better over time. You confirm or fix them.
  • It takes documents from where they already are. A watched folder for your scanner, an Android app for photos, and a mailbox scanner that imports attachments from an email inbox on a schedule.
  • It works for a team. Users belong to a "collective" that shares the same documents, and folders can restrict who sees what.
  • It has an API for anything you want to automate.

Language matters for the smart part. The processing docs say full suggestion models exist for German, English, French and Spanish. Other languages still get OCR and search, but metadata suggestions fall back to simpler rules based on your address book.

The Honest Part: Release Pace

Before you build your filing system on it, know this. Docspell's last stable release is v0.43.0, from March 2025. Since then the project has published nightly builds. Contributors fixed bugs and added features in mid-2026, but most of this autumn's commits are automated dependency updates.

That doesn't make it unsafe to use, and the official Docker setup tracks the latest builds. But it's a smaller, slower project than the most popular alternative. If you want the busiest community and the most frequent releases, look at Paperless-ngx, which we've covered in depth. Docspell is worth it if its approach fits you better: the email import is strong, and the metadata suggestions with an address book suit offices that deal with the same suppliers and clients over and over.

How It's Built

Docspell runs as a few services, which matters when you size a server:

ComponentWhat it does
REST serverThe web app and API, on port 7880
JoexThe worker that runs OCR, conversion and mail imports
PostgreSQLStores documents' metadata and settings
SolrOptional full-text search index
ConsumedirWatches a folder and uploads new files

The worker does the heavy lifting. OCR and conversion are Java and native tools, so give the server enough memory. The compose file even includes a commented option to give Joex more of it.

Getting Started

Docspell on Elestio starts at $11/month for the VM, with backups and updates included. If you run it yourself, the project's Docker setup is the quickest route:

git clone https://github.com/docspell/docker docspell-docker
cd docspell-docker/docker-compose
docker compose up -d

Before you start it on anything reachable from the internet, edit docker-compose.yml. The sample file ships with placeholder secrets such as admin123 and integration-password123, a placeholder database password, and open sign-up. Change these:

  • DOCSPELL_SERVER_ADMIN__ENDPOINT_SECRET and DOCSPELL_SERVER_AUTH_SERVER__SECRET
  • the database password, in both the restserver and joex services
  • the integration header value, in both restserver and consumedir, which must match

Then open http://your-server:7880, create your account, and set DOCSPELL_SERVER_BACKEND_SIGNUP_MODE to closed or invite so strangers can't register.

A Setup That Works for a Small Office

  1. Build the address book first. Add your regular suppliers, clients and organizations. This is what makes the correspondent suggestions useful from day one.
  2. Point your scanner at the watched folder. Many office scanners can save to a network share. Map it to the ./docs folder that the consumedir service watches, and new scans upload themselves.
  3. Set up a mail import. Create a dedicated inbox like invoices@yourcompany.com, then add a Scan Mailbox task. A file filter of *.pdf imports only PDF attachments, and you can have processed mails moved to another folder so they aren't read twice.
  4. Correct the first few dozen suggestions. Docspell learns from your filed documents, so a little effort at the start pays off later.

Troubleshooting

Uploads go in but nothing happens. The worker is either not running or busy. Check docker compose logs joex for OCR or conversion errors.

Search finds nothing in scanned documents. OCR didn't run or used the wrong language. Check the collective's language setting and the Joex logs.

The watched folder doesn't upload. The integration header value in consumedir doesn't match the one in restserver. Make them identical and restart both.

Mail import keeps re-importing the same messages. Mails are left in place and read again. Set the task to move processed mails to another folder, and keep the schedule at least as long as the "received since" window.

Suggestions are poor. Your language may not have a full suggestion model, or the address book is empty. Add your common correspondents and file a few documents by hand.

Thanks for reading ❤️ See you in the next one 👋