DocuBrowse: local, AI-assisted document search without a cloud account

What DocuBrowse is for, and who ends up using it

DocuBrowse targets a specific kind of mess: a directory tree full of PDFs, ebooks, Word documents, spreadsheets, notes and source files where you know the document exists but cannot remember its filename or its exact wording. The README frames the pitch as turning "a messy pile of documents into something you can actually search" and gives the example of asking for "that contract about the lease renewal" and finding it even when those exact words never appear in the file.

The intended user is someone who keeps documents locally and does not want them uploaded. The README states the tool runs entirely on the local machine using local AI models, with no internet connection required, no accounts, no API keys and no per-query costs. That constraint shapes everything else: the search quality you get depends on the models you run locally, not on a hosted service.

It is not a general desktop search replacement. There is no claim of indexing every file on a disk; the README describes pointing the tool at document directories, and the Settings UI supports multiple local or remote folders according to .env.example. The scope is documents and source code, not the whole filesystem.

Two search engines in one query: FTS5 plus Ollama embeddings

The mechanism is a pair of independent scorers. Keyword search runs through SQLite FTS5 over title, author, subject, tags and snippet. Semantic search runs through Ollama embeddings using nomic-embed-text:latest, and the README is explicit about what that layer does: semantic search identifies which documents are relevant, while Deep Links then pinpoints where inside a document the match sits.

Hybrid mode is the default and is described as "Both". Each document takes the stronger of its two scores, with a small boost when both hit, and a document must clear either a keyword hit or a semantic floor to appear in the results. That is a simple merge rule rather than a learned ranker, and the README does not document how the semantic floor is chosen or whether it is tunable.

Synopsis generation is a separate path. Clicking a document title produces a Kindle-style synopsis via Ollama using dolphin3:latest, cached in the database after the first generation. The README warns that the first synopsis for a document may take a while on minimal hardware with CPU only and no GPU, and that later requests are instant because the result is cached. Embeddings come from the second model, so a working install needs both pulled.

Deep Links runs on demand: from any keyword or semantic result you can ask for matching passages inside that document, with no reindexing and no schema change. Each passage shows a sample and a location label of page, line or section, and clicking one opens the passage with the matched text highlighted. The mode follows the search, so a semantic search finds passages by meaning and a keyword or hybrid search finds them by term.

Installing DocuBrowse and running a first search

DocuBrowse ships as packages: RPM, DEB and tarball for Linux, zip for Windows, and dmg for macOS. INSTALL.md at the repository root is the place the project points to for setup, and install.sh sits alongside it. The Python dependencies are listed in requirements.txt, which also names three non-pip prerequisites: Ollama for the local models, Calibre for EPUB, MOBI and AZW3 fallback conversion, and DjVuLibre for .djvu and .djv. All three are described as optional and format-specific.

If you are working from source rather than a package, install the Python dependencies first:

pip install -r requirements.txt

Ollama itself is not a pip package. The README names the two models the app uses, nomic-embed-text:latest for embeddings and dolphin3:latest for synopses, so both need to be available to your local Ollama instance. The repository also contains ensure_ollama.py, which suggests the app checks for a reachable Ollama rather than assuming one.

Document directories are not configured through environment variables. .env.example states plainly that its variables are used only by local dev and test scripts and never by the product at runtime, and that the app always reads its document directories from docubrowse.config or the Settings UI. A minimal configuration file therefore looks like this:

# docubrowse.config
# Document directories are set here or in the Settings UI,
# never through .env at runtime.

The first real use is to point the app at one folder, let it index, and then run a hybrid search. The README's own example query is a good test of whether semantic search is doing anything: ask for "that contract about the lease renewal" and see whether a document whose text never contains those words still surfaces. Then click Deep Links on a result and check that passages come back with page, line or section labels. If Deep Links reports Not Found, the document type is one the project has not yet wired up for passage extraction.

Where DocuBrowse stops: Deep Links coverage and the Docker branch

The most concrete limitation is stated by the project itself. Deep Links may return "Not Found", and the README explains why: the document type has not yet been coded into the mix. In that case the keyword was already assigned to the document, but the tool still cannot read the document body to build passages. The README adds that a PDF which is a picture of the Mona Lisa will likely never be searched this way, which is an unusually direct way of saying that image-only content is out of scope for passage search.

Scanned PDFs are handled differently. The README says image-only PDFs are detected and routed to ocr_list_pdfs.txt, which means they are collected for a separate path rather than silently indexed as empty text.

The second boundary is deployment. The README labels the Docker option experimental and not recommended yet, developed on the docker-experiment branch, and says a fully working model has not been achieved because of Docker and OS limitations combined with the project's security model. The specific failure named is that opening a document in your desktop app does not work from a browser-based container, since the server is headless and the browser is sandboxed. Anyone planning to run this as a shared service should treat that as a blocker rather than a rough edge.

The third boundary is hardware. Synopsis generation on CPU-only machines is slow on first request for each document. The README does not give a figure, so the practical way to judge it is to generate one synopsis on your own machine before committing to a large corpus.

How DocuBrowse differs from Recoll and paperless-ngx

Recoll is the closest thing to a direct alternative in the local search space. It indexes files on your machine with Xapian and returns keyword matches, with no model inference and no embeddings. The difference in approach matters in two ways. Recoll does not need Ollama, a GPU or a model download, so its install is smaller and its behaviour is deterministic. DocuBrowse trades that for semantic similarity, which is the only way a query phrased as "that contract about the lease renewal" can match a document that never uses those words. If your queries are already precise terms you remember, the embedding layer buys you little and costs you a model dependency.

paperless-ngx sits at a different point entirely. It is built around ingesting scanned paperwork into an archive with OCR, tagging and a document management workflow. DocuBrowse does not claim to be a document management system; it indexes documents where they already live and leaves them there, and the README notes it is PII aware and works with multiple document directories. If your problem is a scanner and a filing cabinet, paperless-ngx addresses that. If your problem is that you already have 40 GB of PDFs and ebooks in place and cannot find anything, DocuBrowse addresses that without moving a file.

The honest read is that DocuBrowse's differentiator is the combination of hybrid scoring with on-demand passage search inside a document, not any single component. FTS5 is standard, Ollama embeddings are standard, and the merge rule is simple. The Deep Links layer is the part that is harder to replace.

Maintenance, licensing and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-15, two days before this writing. Releases are frequent and small: v1.5.0 added Korean support and full UI localization on 2026-09-12, v1.5.1 fixed Korean and Japanese search bugs the same day, and v1.5.2 added Chinese language support and multi-lingual man pages on 2026-09-14. The README states that interfaces are stable and breaking changes are avoided where possible, which is a softer promise than a versioning policy.

That release cadence has a practical cost. Localization work touches cjk.py, lang_models.py and the locales directory, and the README instructs contributors to keep README-ja.md, README-ko.md, README-zh.md and README-zh-hant.md in sync with the English file. If you run a modified checkout, expect to rebase against translation and search-relevance changes rather than only against extraction code.

On licensing, the repository's LICENSE file is the authority, and the GitHub metadata reports the license as NOASSERTION, meaning the platform could not classify it automatically. That is not the same as having no license, and it is not the same as a recognised SPDX identifier. If you plan to redistribute DocuBrowse or bundle it into a product, read LICENSE directly and get your own advice; the metadata alone will not tell you whether the terms suit you.

One operational detail worth knowing before you upgrade: the database is a SQLite file, and the repository ships du-docs.db.example plus backup_restore.py and test_backup_restore.py. Backing up the index before a version jump is a supported path rather than something you have to invent.

Editorial conclusion

DocuBrowse suits engineers and researchers with a large local corpus of mixed formats who already run Ollama and want keyword plus semantic search without sending documents anywhere. It is the wrong tool if you need a supported container deployment: the README says the Docker path is experimental and not recommended, and opening a document in a desktop app does not work from a browser-based container. It is also a poor fit if you expect every result to support in-document passage search, because Deep Links returns Not Found for document types that are not yet coded. Before adopting it, verify that Ollama is reachable, that the models named in the README are pulled, and that your file types appear in the supported format list.

Frequently asked questions

Official sources

1. Issues
2. linuxrebel/DocuBrowser on GitHub
3. README
4. Releases