Installation¶

Most people: Docker below, then the user guide. This page is the normal install path. Host Python, pip extras, environment variables, and developer installs are under Advanced.

You also need a running Ollama server and at least one OCR-friendly vision model before the first transcription. Ollama stays on the host whether you use Docker or a native install.

Docker (recommended)¶

No host Python packages. Copy .env.example to .env and set HOST_PROJECTS_DIR to an absolute path outside this repository.

cp .env.example .env          # set HOST_PROJECTS_DIR
docker compose up --build transcribe-web
# → http://127.0.0.1:8510/

Optional inbox and export mounts: HOST_INBOX_DIR, HOST_EXPORT_DIR. Compose notes (Linux extra_hosts, UID/GID, bulk-import paths): docker.md.

After install¶

Confirm Ollama is up: System → Diagnostics, or docker compose exec transcribe-web transcribe models (native: ./transcribe.sh cli models).
Follow From a scan to a readable notebook.
If the first model returns empty text or times out, pick an OCR-oriented tag from the model matrix rather than a general VLM.

Troubleshooting¶

Nothing in the vision picker — Ollama is not reachable, or no vision tag is installed. Default URL: http://localhost:11434 (Docker → host: http://host.docker.internal:11434). Pull an OCR-friendly model, then Refresh on the Transcribe page.
Empty OCR / empty_output — thinking vision models (for example gemma4) often return no text. Prefer OCR-oriented tags. Known limitations.
Docker cannot see notebooks — HOST_PROJECTS_DIR must be an absolute path outside the repo. docker.md.
“No module named streamlit” after a manual pip install — install the UI extra: pip install -e '.[ui]', or re-run ./transcribe.sh setup.

Advanced¶

Native on the host (Python)¶

Python 3.10+. There is no published PyPI package — clone this repository. Prefer this path for local development, not as the everyday install.

cd /path/to/transcribe
cp .env.example .env          # optional path / Ollama overrides
chmod +x transcribe.sh
./transcribe.sh setup         # creates .venv and installs the UI extra
./transcribe.sh ui            # → http://127.0.0.1:8510/

Point notebooks, scans, and exports outside the clone when you want data to survive repo wipes:

# in .env
TRANSCRIBE_PROJECTS_DIR=/Users/you/Documents/transcribe-projects
TRANSCRIBE_INBOX_DIR=/Users/you/Documents/notebook-scans
TRANSCRIBE_EXPORT_DIR=/Users/you/Documents/transcribe-exports

Manual venv¶

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[ui]'
# developer extras: pip install -e '.[dev]'
# EPUB without Streamlit: pip install -e '.[export]'

./transcribe.sh install-dev installs .[dev]. Console scripts after install: transcribe, transcribe-ui.

Install extras¶

Extra	What it adds
(core)	Pillow, PyMuPDF, wordcloud — CLI OCR / text+PDF export without Streamlit
`[ui]`	Streamlit + pydantic + ebooklib (primary interactive surface)
`[export]`	ebooklib for EPUB without pulling Streamlit
`[dev]`	pytest, ruff, coverage + UI extras
`[docs]`	Sphinx (`make docs`); not required to run the app

Environment variables¶

Copy .env.example → .env. Repo-root .env is loaded without overriding variables already set in the shell or Compose.

Variable	Role
`TRANSCRIBE_PROJECTS_DIR`	Notebook projects root
`TRANSCRIBE_INBOX_DIR`	Optional scans inbox
`TRANSCRIBE_EXPORT_DIR`	Optional export root
`TRANSCRIBE_DATA_DIR`	Workspace data (caches, config, corpus)
`TRANSCRIBE_OLLAMA_BASE_URL`	Ollama server root URL
`TRANSCRIBE_HOST` / `TRANSCRIBE_PORT`	UI listen (default port 8510)
`TRANSCRIBE_BIND_HOST`	Compose publish bind (default `127.0.0.1`)
`TRANSCRIBE_PYTHON`	Interpreter for `transcribe.sh` venv creation

Docker host mounts use HOST_* counterparts — docker.md.

First checks (CLI)¶

# Docker
docker compose exec transcribe-web transcribe models
docker compose exec transcribe-web transcribe doctor /mnt/projects/my-notebook
docker compose exec transcribe-web transcribe corpus-doctor

# Native
./transcribe.sh cli models
./transcribe.sh cli doctor "$TRANSCRIBE_PROJECTS_DIR/my-notebook"
./transcribe.sh cli corpus-doctor

Developer loops: developer quickstart.