bookreader-tui

A terminal EPUB reader and personal library, built with Textual.

Open an EPUB in a focused two-column or two-page TUI, remember where you left off, organize what you've read into a small SQLite library, and render figures inline in kitty, iTerm2, WezTerm, or any sixel-capable terminal — automatically, with placeholders elsewhere.

pipx install bookreader-tui && bookreader path/to/book.epub

Why bookreader-tui?

• vs Calibre — no Qt, no GUI process, no separate viewer. Lives in your terminal where the rest of your workflow already is.
• vs epy — full library: collections, ratings, wishlist, reading-time stats, bookmarks with notes, multi-book session continuity.
• vs mdcat / piping to a pager — proper EPUB rendering (chapters, TOC, two-page mode, inline images) instead of a flat text dump.
• vs reading on your phone — keyboard-driven, distraction-free, themed, scriptable. Your reading position syncs by EPUB identifier so the same book at a different path resumes in the same place.

Features

• Distraction-free reader — centered reading column with a typographically sane width cap, TOC sidebar, optional two-page spread.
• Persistent position — picks up exactly where you left off, per book, identified by EPUB dc:identifier.
• Library — SQLite-backed, with collections (Currently Reading, Finished, Want to Read), ratings, bookmarks with notes, per-book reading time.
• Wishlist books — track titles you intend to read before you have the file. Attach a real EPUB later.
• Inline images — kitty / iTerm2 / WezTerm / sixel via textual-image; auto-detected, runtime-toggleable with I.
• Three built-in themes (dark, light, sepia) plus the standard Textual command palette.
• Pure Python, no external services — your library lives in ~/.local/share/bookreader/. Nothing leaves your machine.

Install

The PyPI package is named bookreader-tui. The bare bookreader name was already taken on PyPI; the import path and the console script are still bookreader.

Recommended: pipx or uv tool

For end-user CLI tools, prefer an isolated install over pip install into your system Python — that path is blocked on most modern Linux distros by PEP 668 anyway.

# pipx (most popular)
pipx install bookreader-tui

# OR uv tool (faster, same idea)
uv tool install bookreader-tui

Either gives you a global bookreader command with its dependencies sandboxed in their own venv.

pip (inside a venv)

If you're already managing a virtualenv:

python -m venv .venv
source .venv/bin/activate          # Linux/macOS
# .venv\Scripts\activate           # Windows
pip install bookreader-tui

From source

git clone https://github.com/prajwalmahajan101/BookReader
cd BookReader
pipx install -e .                  # or: pip install -e . inside a venv

Requirements

• Python ≥ 3.11
• A terminal with at least 80 columns. 120+ recommended.
• For inline images: kitty, iTerm2, WezTerm, Ghostty, or a sixel-capable terminal (foot, mlterm, xterm with --enable-sixel-graphics, Konsole, Windows Terminal).

Quick start

# Open a book directly — gets added to your library on first open
bookreader path/to/book.epub

# Land on the library home; pick a book with Enter
bookreader

# One-off read without touching the library
bookreader --no-library path/to/book.epub

That's it. Position, bookmarks, and reading time persist automatically.

Inline images — terminal setup

bookreader ships inline-image rendering via textual-image. On launch it sniffs your terminal and enables images if it recognizes a graphics-capable one.

What works out of the box (no config)

Sixel terminals (force-enable)

foot, mlterm, xterm (built with --enable-sixel-graphics), mintty, Contour, Windows Terminal. Auto-detection doesn't cover these — set the override:

BOOKREADER_IMAGES_ENABLED=1 bookreader path/to/book.epub

Terminals without graphics support

Anything else (e.g. plain xterm, gnome-terminal, Terminal.app, tmux without a graphics-capable host) renders figures as [image: alt] placeholders. Everything else works normally.

Toggle at runtime

Press I inside the reader to flip images on/off mid-session — useful for comparing or when an image is breaking your layout.

Screenshots

Scroll mode	Two-page spread

Key bindings

Reader

Scrolling past the end of a chapter flows into the next one; going back from the start flows into the previous chapter's end.

Library

CLI subcommands

bookreader add path/to/book.epub                          # add without opening
bookreader add --wishlist --title "T" --author "A"        # phantom entry, no file
bookreader attach <book-id> path/to/book.epub             # promote a wishlist row
bookreader list                                           # print every book
bookreader stats                                          # minutes read per book
bookreader --version

Configuration

All settings are environment variables prefixed BOOKREADER_. Set them in your shell rc, your .env, or per-invocation:

File locations (XDG)

Honors XDG_DATA_HOME and XDG_STATE_HOME if set. Safe to back up the whole ~/.local/share/bookreader/ directory.

Upgrading from 0.x JSON store

On first launch the library service migrates ~/.local/state/bookreader/positions.json entries that match books already added; the JSON is renamed to positions.json.migrated once data flows. No manual step needed.

Troubleshooting

bookreader: command not found You installed with pip install bookreader-tui directly into your system Python and PEP 668 blocked it, or you installed into a venv that isn't activated. Use pipx install bookreader-tui (recommended) or activate the venv.

Images render as [image: alt] placeholders even in kitty Check that the env var hasn't been turned off: echo $BOOKREADER_IMAGES_ENABLED. If it's set to 0, unset it or set to 1. Inside the reader, press I to force-toggle. If it still doesn't render, your kitty session may be inside tmux/screen without graphics passthrough — start kitty directly to test.

Images render at low quality The image is being upscaled into a column that's too narrow. Raise BOOKREADER_READING_WIDTH (try 140 or 160) and re-launch.

q quits while I'm typing in a wishlist title It shouldn't — modals isolate keystrokes. If you hit this, please open an issue with your terminal + Textual version.

My EPUB has no images at all Confirm: bookreader list shows it. Then python -c "from ebooklib import epub; b=epub.read_epub('path.epub'); print(sum(1 for i in b.get_items() if i.media_type.startswith('image/')))". If that prints 0, the EPUB itself has no embedded images.

Library got corrupted Stop the app. Move the file aside: mv ~/.local/share/bookreader/library.db ~/.local/share/bookreader/library.db.bak. Re-launch — a fresh library is created. Use bookreader add <path> to repopulate.

I want a clean slate rm -rf ~/.local/share/bookreader ~/.local/state/bookreader. Removes the library, positions, and logs.

Development

git clone https://github.com/prajwalmahajan101/BookReader
cd BookReader
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

# The full local gate (matches CI):
pytest -q
ruff format --check . && ruff check src/ tests/
mypy src/

Project layout

src/bookreader/
  core/      # config, paths, logging, exceptions    (no I/O)
  epub/      # parsing + rendering                   (no UI, no DB)
  state/     # JSON position + bookmark fallback
  library/   # SQLite library: db, repo, service, migrations
  ui/        # Textual app, screens, widgets, themes
tests/
  unit/         # parsers, renderer, config
  integration/  # service + screen pilot tests
docs/adr/    # architecture decision records

UI never imports a repository directly — it talks to a service.

Releasing

Tag-driven, fully automated:

# Bump version in src/bookreader/__init__.py and pyproject.toml,
# add a [X.Y.Z] section to CHANGELOG.md, commit, then:
git tag -a vX.Y.Z -m "Release X.Y.Z"
git push origin main vX.Y.Z

.github/workflows/release.yml builds the sdist + wheel, verifies the tag matches pyproject.toml, publishes to PyPI via trusted publishing, and creates a GitHub Release with the CHANGELOG-extracted notes and dist files attached.

Project background

Built solo as a phase-driven exercise: each phase is a feature branch with its own ADR, atomic commits, and merge-clean history.

• Phase 1 — Reader Core
• Phase 1.5 — Two-page mode
• Phase 2 — SQLite Library
• Phase 3 — Polish (bookmarks, sessions, phantom books, inline images)
• Phase 4 — Library curation (collections + wishlist overview)
• Phase 5 — UX polish + first PyPI release as bookreader-tui

Architecture decisions live in docs/adr/. Version-by-version notes in CHANGELOG.md.

License

Apache-2.0 — Copyright 2026 Prajwal Mahajan.