linuxrebel/DocuBrowser: This does for Documents what repo-browser does for repos. A local AI powered Document search engine · GitHub

Packaged for Linux (RPM, DEB, tarball), Windows (zip), and macOS (dmg).
Interfaces are stable; breaking changes are avoided where possible.

DocuBrowse turns a messy pile of documents into something you can actually search.
Point it at your files — PDFs, ebooks, Word docs, notes, whatever — and it builds a smart
index that understands not just keywords, but meaning. Ask for “that contract about the
lease renewal” and find it even if those exact words never appear. Click any result for
an instant AI summary before you even open the file. PII aware and works with multiple document directories.

DocuBrowse runs entirely on your own machine using local AI models — no internet
connection required, no accounts, no API keys, and no per-query costs eating into a
token budget. Your data. Your AI.

Under the hood: SQLite FTS5 keyword search plus AI-powered semantic similarity and
synopsis generation (Ollama + nomic-embed-text + dolphin3). Supports multiple document and source code types.

↑ Top

• Keyword Search — fast full-text search via SQLite FTS5 (title, author, subject, tags, snippet)
• Semantic Search — AI-powered similarity via Ollama embeddings (nomic-embed-text:latest)
• Hybrid Mode (default) — 70% semantic + 30% keyword, merged and re-ranked

• Click any document title for a Kindle-style book-jacket synopsis, generated on demand
  via Ollama (dolphin3:latest) and cached in the database after first generation.
  Semantic search embeddings are produced by a second local model (nomic-embed-text:latest)

• Formats: PDF, DOCX, PPTX, XLSX, EPUB, MOBI, AZW3, AZW, HTML, TXT, Markdown
• PDF intelligence: pdfplumber (preferred) with pypdf fallback for bloated-object files; layout=False retry for complex layouts; scanned (image-only) PDFs detected and routed to ocr_list_pdfs.txt
• Word documents: python-docx extracts paragraphs, tables, and core properties (title, author, subject)
• Presentations: python-pptx extracts slide text, notes, and core properties
• Spreadsheets: openpyxl extracts cell values and sheet names
• E-books: ebooklib for EPUB; mobi package + Calibre fallback for MOBI/AZW3; DRM-encrypted AZW files indexed with metadata only (title/author visible, body not searchable)
• Metadata: title, author, subject extracted from document metadata fields; auto-generated tags from directory structure and content keywords
• PII protection: post-ingest scanner detects SSN, credit card, bank routing/account number, DOB, MRN, driver license, passport patterns; removes matching documents and permanently blacklists them

• Dark/Light theme toggle
• Paginated results (50 docs/page) with Back/Next controls
• Alphabetic index bar (A–Z, 0–9) for quick navigation, with state preserved across page loads; Home button to reset
• Tag cloud for filtering by topic
• Relevance score badges (0–100%) on every result
• Open button on each result card — launches the file in your default app via xdg-open
• Click document title for an AI synopsis; 📋 copies path to clipboard; 🗑 deletes file from disk and index (with confirmation)
• Moved/deleted documents: clicking a doc whose file no longer exists shows a dismissable
  modal (and removes it from the index on dismiss) if its filesystem is mounted, or a
  toast (no index change) if the filesystem can’t be verified (e.g. unmounted drive)

• General panel: document directory (with live directory browser), any number of additional scan directories (added/removed under the same panel — automatically included in scan/rescan, no extra command needed), working directory, and port
• Ignored Directories panel: browse to add a directory to ignore_dirs.txt, with a confirmation prompt before purging already-indexed documents under it, and a confirmation before removing an entry

• Search latency: <150ms typical
• Parallel PDF extraction with ProcessPoolExecutor (physical-core-aware worker count)
• Memory-safe: kernel-enforced RLIMIT_AS (6 GB/worker) + pause/resume on free-RAM threshold

↑ Top

Click any thumbnail to view full size.

Dark Mode	Light Mode

Settings	AI Synopsis

Settings is a standalone page at /settings (opened in a new tab via the gear icon). The General panel covers the document directory (with live directory browser, plus any number of additional scan directories), working directory, and port; the Ignored Directories panel manages scan exclusions, each with a directory browser, add/clear controls, and confirmation before removal.

↑ Top

• Python 3.9+
• pdfplumber, pypdf — PDF extraction
• python-docx — Word documents
• python-pptx — PowerPoint presentations
• openpyxl — Excel spreadsheets
• ebooklib, beautifulsoup4, mobi — E-books
• psutil — cross-platform process and hardware detection
• Calibre — E-book metadata and conversion (required for MOBI/AZW3/AZW indexing):
  sudo dnf install calibre or sudo apt install calibre
• Ollama — installed automatically by docubrowser start if missing
• Modern browser (Chrome, Firefox, Safari, Edge)

See INSTALL.md for a full step-by-step guide.

DocuBrowse ships as RPM, DEB, tarball, Windows zip, and macOS dmg packages.
Download the appropriate package from the
Releases page.

# Fedora / RHEL
sudo dnf install ./docubrowser-foss-0.9.0-7.noarch.rpm

# Debian / Ubuntu / Mint
sudo apt install ./docubrowser-foss_0.9.0-7_all.deb

# Any Linux (tarball)
tar xzf docubrowser-foss-0.9.0-7.tar.gz
cd docubrowser-foss-0.9.0-7
sudo ./install.sh

Windows: Extract the zip, then double-click Install.bat. Requires
Python 3.9+ and Ollama to be pre-installed. Installs to
%USERPROFILE%\DocuBrowse with a Start Menu shortcut — no admin required.
You may need to log out and back in for the shortcut to appear.

macOS: Open the dmg, then double-click Install.command (right-click →
Open the first time — the scripts are unsigned). Requires Python 3.9+.
Installs to ~/Applications/DocuBrowse/ with a Python virtualenv, CLI
wrappers at /usr/local/bin/docubrowser and /usr/local/bin/docuback
(sudo prompted; falls back to ~/bin/ if declined), and a DocuBrowse.app
launcher that starts the server and opens the web UI in Terminal.

All Linux methods install to /opt/docubrowser/ with a Python virtualenv,
CLI wrappers at /usr/bin/docubrowser and /usr/bin/docuback, a desktop
menu entry under Office, and all Python dependencies from requirements.txt.

Once installed, the CLI is the docubrowser command — drop the ./ and .py
from every example below. For example, docubrowser start and
docubrowser rescan. The ./docubrowser.py form shown throughout the
rest of this README is the dev / cloned-repo path (running directly out of a
checkout).

To uninstall: sudo dnf remove docubrowser-foss (RPM),
sudo apt remove docubrowser-foss (DEB), sudo ./uninstall.sh (tarball),
double-click Uninstall.bat (Windows), or double-click Uninstall.command
(macOS — on the dmg or in ~/Applications/DocuBrowse/).

cd /path/to/DocuBrowse

# Scan and index your documents
./docubrowser.py rescan

# Start the server
./docubrowser.py start

# Open the UI
./docubrowser.py open

On an installed system, use the docubrowser command instead, e.g.
docubrowser rescan / docubrowser start / docubrowser open.

docubrowser.py start automatically verifies Ollama is installed, running, and has
both required models — nomic-embed-text:latest (embeddings) and
dolphin3:latest (synopsis generation) — installing/starting/pulling
as needed.

↑ Top

Usage: docubrowser.py  [options]

--db PATH      SQLite database path (overrides config)
--port PORT    Server port (overrides config)
--config FILE  Config file path

# Server management
./docubrowser.py start
./docubrowser.py start --port 9000
./docubrowser.py status
./docubrowser.py stop
./docubrowser.py stopall

# Scanning
./docubrowser.py scan                          # scan all supported types
./docubrowser.py scan pdf                      # PDFs only
./docubrowser.py scan pdf txt                  # PDFs and plain text
./docubrowser.py scan --limit 100              # first 100 unindexed files only
./docubrowser.py rescan                        # scan + embed all types
./docubrowser.py rescan pdf --workers 4        # PDFs only, 4 workers
./docubrowser.py rescan --no-embed             # scan without embedding step
./docubrowser.py rescan --doc-dir /data/docs

# Single-file indexing (useful for retrying blacklisted files)
./docubrowser.py scan-file --file /path/to/document.pdf
./docubrowser.py scan-file --file /path/with spaces/doc.pdf   # no quoting needed
./docubrowser.py scan-file --file /path/to/doc.pdf --no-embed

# Reporting and maintenance
./docubrowser.py report                         # file-type breakdown, no DB changes
./docubrowser.py embed                          # embed any un-embedded docs
./docubrowser.py purge --dry-run               # preview PII matches (safe)
./docubrowser.py purge                         # remove PII documents (prompts)

# Excluding directories from scanning
./docubrowser.py ignore add /mnt/data/Documents/myWorkDocs   # exclude + purge indexed docs under it
./docubrowser.py ignore list                                  # show ignored directories
./docubrowser.py ignore remove /mnt/data/Documents/myWorkDocs # re-allow (rescan to re-index)

# Duplicate detection and cleanup
./docubrowser.py duplist                       # find exact SHA256 duplicates
./docubrowser.py duplist --near-dups           # also find near-duplicates (cosine ≥97%)
./docubrowser.py duplist --near-dups --threshold 0.95
./docubrowser.py dupclean                      # interactive Keep A/Keep B/Keep Both TUI
./docubrowser.py dupclean --near-dups          # include near-duplicates in cleanup

# Cleaning up moved/deleted documents (opt-in, not run automatically)
./docubrowser.py scan-missing --dry-run        # report counts only, no DB changes
./docubrowser.py scan-missing                  # delete rows for genuinely-missing files

Types: pdf  txt  md  html  (default: all four)

Examples:
  rescan pdf             PDFs only
  rescan pdf txt         PDFs and plain text
  rescan                 all supported types (prompts if unfiltered)

scan-file is designed for retrying individual problem files:

• Removes the file from scan_blacklist.txt if listed (explicit retry)
• Refuses files in pii_blacklist.txt (permanent PII block)
• Detects scanned (image-only) PDFs → adds to ocr_list_pdfs.txt
• Paths with spaces work without quoting: --file accepts multiple tokens and rejoins them

↑ Top

DocuBrowse reads the first config file it finds:

1. /etc/docubrowse.config (system-wide)
2. ./docubrowse.config (next to docubrowser.py)

If neither exists, built-in defaults apply — except doc_dir, which has no
default. Until a document directory is configured (via the Settings gear icon
in the web UI, or by setting doc_dir in docubrowse.config), the web UI
shows a banner prompting you to configure one, and CLI commands that need a
document directory (rescan, report, scan) exit with an error explaining
how to set it.

# docubrowse.config
doc_dir      = /mnt/data/Documents
db_path      = /home/user/DocuBrowse/du-docs.db
port         = 8643
work_dir     = /home/user/DocuBrowse