bookserver

A small local web app that serves a folder of EPUB books as a Calibre-style cover grid. Point it at a library folder and it shows the covers with title and author, lets you navigate subfolders, search the whole library, and download any book by clicking its cover.

Features

• Cover grid — extracts each book's cover and shows it with title/author.
• Folder navigation — browse subfolders like a file browser, with breadcrumbs.
• Global search — search the entire library by title, author, or filename.
• One-click download — click a cover to download the original .epub.
• Fast — covers are thumbnailed and cached on disk; book metadata is indexed in the background, so browsing stays responsive even for large libraries.

Requirements

• uv
• Python 3.12+ (uv will fetch it if needed)

Usage

uv run bookserver /path/to/your/books

Then open http://127.0.0.1:8000.

Options:

uv run bookserver /path/to/your/books --host 0.0.0.0 --port 9000

• --host — interface to bind (default 127.0.0.1; use 0.0.0.0 to reach it from other devices on your network, e.g. a phone or tablet).
• --port — port to listen on (default 8000).

Caches (cover thumbnails and the metadata index) are stored in your platform's per-user cache directory and never written into the book folders.

Development

uv sync
uv run pytest

The code is split into focused modules under src/bookserver/:

• epub.py — parse title/author/cover from an EPUB.
• library.py — folder listing, recursive walk, path-traversal guard.
• covers.py — cover thumbnail cache.
• index.py — persistent SQLite metadata index and search.
• app.py — FastAPI routes, templates, and the CLI.