Docspell: A Self-Hosted Document Organizer Built Around OCR and Stanford CoreNLP
Assist in organizing your piles of documents, resulting from scanners, e-mails and other sources with miminal effort.
At a glance
- What is it?
- Docspell targets households and small groups that scan paper, receive PDFs by mail, and then lose track of both. It combines a Scala backend, an Elm SPA, tesseract-based OCR and CoreNLP-driven metadata suggestions, and it ships under AGPL-3.0.
- Who is it for?
- Adopt Docspell if you want a self-hosted place to dump scanner output and email attachments and have correspondents, tags and dates suggested rather than typed, and if you accept AGPL-3.0 plus a Java/Scala runtime with external binaries. Do not adopt it if you need records-retention compliance, workflow approvals or a vendor SLA; the README offers none of these.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly Elm, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Docspell addresses: metadata, not storage
Storing scanned paper is easy. Finding it again is the hard part, and the README is explicit about why: associating tags, correspondents and dates to a document manually is a tedious task. Docspell's pitch is that it can suggest correspondents, guess tags and find dates using machine learning, learning from documents you have already processed. That framing matters, because it separates Docspell from a plain file server with a search box. The project describes itself as a personal document organizer, sometimes called a Document Management System, and states it is targeted for home use: families, households and smaller groups or companies. It expects you to already own a scanner, and it expects the input to arrive from several places at once, including scanners, emails and other sources. If you have one folder of PDFs and a working filename convention, Docspell is more machinery than the problem requires.
Architecture: Scala services, an Elm SPA, and external binaries doing the heavy lifting
The README describes Docspell as an orchestration of other tools rather than a monolith that implements everything itself. The backend is Scala written in a pure functional style on the typelevel stack: Cats, FS2, Doobie, Http4s, Circe and Pureconfig. The web frontend is a single-page application in Elm, styled with tailwind. Machine learning features come from the Stanford Core NLP library, which the README notes is GPL-licensed. File processing is delegated to external programs, named in the README as tesseract, unoconv and ocrmypdf. That delegation is the architectural fact worth internalising: OCR quality, PDF conversion and text extraction are not Docspell's code, so their behaviour on your documents is a function of the versions installed on your host. Everything is reachable through a REST/HTTP API, which is how the separate Android client and the dsc command line tool talk to it. The dependency list lives in project/Dependencies.scala if you want to audit versions before deploying.
Getting it running: three commands, then a signup form
The README gives a docker-compose path as the quickest start, and it is short enough to quote in full. Clone the docker repository, change into its docker-compose directory, and bring it up:
git clone https://github.com/docspell/docker docspell-docker cd docspell-docker/docker-compose docker-compose up -d
Then open http://localhost:7880, sign up and log in. The README adds a specific instruction for this first login: use the same name for collective and user for now. That detail is easy to skim past and will cost you time if you do not follow it. Other installation routes are documented on the project's quickstart page: a deb package for Debian-based systems, a zip file whose bin/ script you run, a nix package with a NixOS module, and a Helm chart in the same docker repository. The releases page is where the deb and zip artifacts are published. Note that the docker-compose file is maintained in a separate repository from the server code, so the image tag it pins and the tag you read about in release notes can drift apart.
What the nightly tag implies about upgrade discipline
The release list shows a nightly build dated September 2026 alongside two numbered releases, v0.43.0 from March 2025 and v0.42.0 from August 2024. The gap between numbered releases is measured in months, and a nightly channel exists in parallel. For an operator this is the practical question: whether your deployment tracks numbered tags or floats on nightly. The README does not describe a migration or backup procedure, and it does not state a supported upgrade path between versions, so the material here cannot tell you whether a jump from 0.42.0 to 0.43.0 is routine or requires manual database work. Treat that as unverified and check the project documentation before upgrading a system holding documents you cannot re-scan. The same caution applies to the external tools: a tesseract major version change on the host can alter extracted text without any Docspell release being involved.
Where Docspell is the wrong choice
The README's own scope statement is the clearest limitation: home use, families, households, smaller groups. Nothing in the material describes retention schedules, legal hold, audit trails, role-based approval chains or any compliance certification. If your requirement is a records system that a regulator or an auditor will inspect, Docspell's feature list as presented here does not address it, and the AGPL-3.0 licence adds a second consideration for anyone embedding it in a commercial offering. There is also an operational cost that the three-command quickstart hides. You are running a Scala service plus a database plus whatever tesseract, unoconv and ocrmypdf need, and CoreNLP is a Java library with its own memory footprint. On a small VPS this is a real resource commitment for what is, at the end of the day, a household filing cabinet. The ML suggestions are described as suggestions; the README does not claim they are correct, and a system that guesses correspondents will occasionally guess wrong, which means someone still reviews the output.
How it differs from a plain searchable file index
The obvious alternative for a household is a directory tree plus a desktop full-text indexer such as Recoll or DocFetcher, or a note-taking tool with attachment support. The difference is in where the metadata lives and who produces it. A file indexer reads what is already in your files and returns matches; it does not propose that this letter is from your insurance company and belongs under a particular tag. Docspell's stated approach is to learn metadata from existing documents and then apply that learning to new arrivals, which is why the CoreNLP dependency exists at all. The trade-off is inverted: the indexer has almost no setup and no state beyond its index, while Docspell asks you to run services, keep a database, and train it by curating documents before the suggestions become useful. The first hundred documents are work. The alternative that avoids both is disciplined naming and folders, which costs nothing to run and nothing to maintain, and fails the moment a second person in the household needs to find something.
Licence and long-term maintenance
Docspell is distributed under AGPLv3 or later, per the README and the SPDX identifier AGPL-3.0-or-later. For a household running it on its own hardware this is unremarkable. For a small company that wants to offer document handling to customers as a hosted service, the network-copyleft terms are the thing to read carefully, and this article is not legal advice. On maintenance, the repository is not archived and last saw a push in September 2026, with a nightly release the same month. The dependency situation is the part that ages fastest: the backend pulls from the typelevel ecosystem, the frontend is Elm, and the ML layer depends on Stanford CoreNLP, which the README identifies as GPL. That is three separate upgrade tracks plus the external OCR binaries. A Scala Steward badge in the README indicates automated dependency update pull requests are configured, which is a signal about process rather than about any particular version being current.
Editorial conclusion
Adopt Docspell if you want a self-hosted place to dump scanner output and email attachments and have correspondents, tags and dates suggested rather than typed, and if you accept AGPL-3.0 plus a Java/Scala runtime with external binaries. Do not adopt it if you need records-retention compliance, workflow approvals or a vendor SLA; the README offers none of these. Before committing, read the docs/install/quickstart page for your platform, confirm which external tools your host provides (tesseract, unoconv, ocrmypdf), and check that the nightly build tag is not what your docker-compose file pulls by default.
Community notes