Docspell

Last reviewed Sep 13, 2026 · 784 words

Docspell wants 2 GB of RAM and at least three containers, which is roughly double what Paperless-ngx asks for the same job. In exchange you get the smartest automatic metadata in the self-hosted document space: upload a scanned electricity bill and Docspell proposes the correspondent, the date, the tags, and a due date, learned from the documents you have already filed, before you touch a single field. Whether that trade is worth it comes down to how many documents you process a month and how much you dislike typing.

Three moving parts, plus a database

The architecture is the first thing to understand, because it is the source of both the resource use and the reliability. The REST server (port 7880) serves the API and the Elm-written web UI. The job executor, called joex (port 7878), does everything heavy: OCR with Tesseract, PDF conversion with OCRmyPDF, office-document conversion through LibreOffice, text analysis, and the classifier training. Both are JVM applications written in Scala, and both need a shared PostgreSQL database (MariaDB and H2 are supported, PostgreSQL is the sane choice). Full-text search uses either PostgreSQL's built-in search or an Apache Solr container if you want better ranking on a large archive.

A minimal compose file runs restserver, joex, and PostgreSQL. Add a small dsc watcher container if you want a folder that ingests anything dropped into it by a scanner. That is 3 to 4 containers where Paperless-ngx runs comfortably in 2. Joex is the memory hog: the JVM heap plus Tesseract plus LibreOffice during a conversion is where the 2 GB goes, and I would not run it on a 4 GB box that does anything else.

The auto-suggestions are the point

Docspell's metadata model has organisations, persons, equipment, folders, and tags, and every uploaded document gets suggestions for each. The mechanism is partly rule-based, matching names from your address book against the OCR text, and partly a classifier that retrains on a schedule using your existing filed documents. After about 50 filed items from a given correspondent, its suggestions for that correspondent become reliable enough that filing is one click on "confirm". Dates come from the text, and multiple candidates are offered when the document contains several.

Custom fields (amounts, invoice numbers, typed values) round it out, and the search syntax lets you write queries such as corr:"City Water" date>2025-01-01 tag:invoice from the search bar. Multi-user is native, with collectives as the tenancy boundary, so two households or a small firm can share one instance without seeing each other's files. The API is complete enough that the Android app and the CLI are both built on it.

What it is worse at

The interface is functional rather than pretty, and Elm's single-page approach means it is fast once loaded but unfamiliar to people who expect a document to open in a new tab. Mobile use is through a separate app rather than a responsive layout. Bulk operations on hundreds of documents are slower than in Paperless-ngx. And the ecosystem is thin: one main developer, 2,324 stars, AGPL-3.0, steady but not fast releases, and no equivalent of the plugin and consumption-template community that has grown around Paperless.

Category placement is worth a note: this is a document manager, not an ebook tool, and the real peers are in the document management category. If you also want to shelve EPUBs, run something else beside it.

Paperless-ngx is the safer default

The Paperless-ngx setup guide covers the more common choice, and for most people it is the right one: lighter, a far larger community, more integrations, and matching rules that get you 80 percent of Docspell's automatic filing with some manual setup. Docspell earns its extra memory when the volume is high enough that per-document typing hurts, or when you want the automatic correspondent and date detection to work from day one without writing matching rules yourself. Papermerge is the third option in this space but has churned through rewrites; I would not put it ahead of either.

What I'd do

If you file more than 30 documents a month and have 2 GB to spare, run Docspell with PostgreSQL, feed it a folder via dsc watch, spend the first weekend confirming suggestions so the classifier has something to learn from, and back up both the database and the file store together. If you file 5 documents a month, or the box is already tight on memory, install Paperless-ngx and do not look back.