bookokrat 0.3.8

A terminal-based EPUB/PDF Books reader
Documentation

Bookokrat

Terminal EPUB/PDF/DJVU reader focused on speed, smooth navigation, and Vim-style workflows.

https://github.com/user-attachments/assets/0ebe61c6-4629-4bde-8bd4-50feb9a424a3

Highlights

  • EPUB, PDF, and DJVU support in one TUI app
  • Split layout: library/TOC on the left, reader on the right
  • Fast PDF/DJVU pipeline with Kitty SHM image transfer in supported terminals
  • Search, bookmarks, jump list history, reading stats
  • Inline comments/annotations with persistent storage and Markdown export
  • Image rendering, link handling, and external viewer handoff
  • Theme selection, adjustable margins, zen mode
  • Vim-style keybindings and normal mode

Install

Homebrew (macOS)

brew install bookokrat

Arch Linux (AUR)

Install from the AUR:

yay -S bookokrat-bin
# or
paru -S bookokrat-bin

Nix / NixOS (flakes)

nix run github:bugzmanov/bookokrat
# or install into profile
nix profile install github:bugzmanov/bookokrat

Prebuilt Linux binaries

Download from GitHub Releases.

Cargo (all platforms)

Build from source. Requires Rust and a C compiler/linker.

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install build-essential

# For PDF / DJVU support:
sudo apt install pkg-config libfontconfig1-dev clang libclang-dev

Linux (Fedora/RHEL):

sudo dnf install gcc make

macOS:

xcode-select --install

Windows: Install Visual Studio Build Tools with the "Desktop development with C++" workload.

Windows notes:

  • PDF/DJVU might not work in Windows PowerShell.
  • For full Kitty graphics protocol support, consider using WSL with Ghostty or Kitty.
  • If MuPDF fails to build, disable PDF/DJVU support: cargo install bookokrat --no-default-features
cargo install bookokrat

Build without PDF / DJVU support:

cargo install bookokrat --no-default-features

Quick Start

bookokrat

Optional direct open:

bookokrat path/to/book.epub
bookokrat path/to/book.pdf
bookokrat path/to/book.djvu
bookokrat path/to/book.epub --zen-mode

Press ? inside the app to open the built-in help.

Documentation

Terminal Notes

PDF and DJVU viewing require a graphics-capable terminal.

  • Best experience: Kitty, Ghostty
  • Good: iTerm2, WezTerm, Warp, Konsole (with some limitations)
  • Terminals without graphics protocol support - EPUB support without images. PDFs and DJVUs are not supported

For protocol details and troubleshooting, see the in-app help (?) and readme.txt.

Data Storage

Bookokrat stores state in XDG-compliant locations and keeps project directories clean.

Data Location
Bookmarks <data_dir>/bookokrat/libraries/<library>/bookmarks.json
Comments <data_dir>/bookokrat/libraries/<library>/comments/
Image cache <cache_dir>/bookokrat/libraries/<library>/temp_images/
Log file <state_dir>/bookokrat/bookokrat.log
Settings ~/.bookokrat_settings.yaml

Typical <data_dir> paths:

  • macOS: ~/Library/Application Support
  • Linux: ~/.local/share

Vendored Dependency Notice

tui-textarea is vendored in vendor/tui-textarea because upstream is currently unmaintained and behind current ratatui compatibility. The vendored base comes from PR #118: https://github.com/rhysd/tui-textarea/pull/118/changes

Attribution

Bookokrat is based on bookrat by Dmitry Sobolev (MIT).

License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE.