opdsdir

Generates an OPDS Atom catalog (catalog.xml) for a local directory of ebooks. Runs incrementally — only changed or new files are reprocessed.

Supported formats: epub, pdf, mobi, azw/azw3, fb2, cbz, cbr, djvu, lit

Requirements

uv — dependencies are declared inline (PEP 723) and installed automatically on first run.

Usage

chmod +x opds_gen.py

# Generate / update catalog
./opds_gen.py /path/to/books

# With a base URL (needed for OPDS clients to fetch files)
./opds_gen.py /path/to/books --base-url https://example.com/books

# Force full rescan (ignore cached state)
./opds_gen.py /path/to/books --base-url https://example.com/books --force

# Verbose output (shows cover strategy, skipped files, etc.)
./opds_gen.py /path/to/books --verbose

Output is written into the book directory itself:

Path	Description
catalog.xml	OPDS Atom feed — point your reader here
.opds_state.json	Incremental update cache
.covers/<hash>.jpg	Extracted cover images (EPUB only)
.covers/<hash>_thumb.jpg	Thumbnails

Automatic updates

systemd path unit (recommended)

sudo cp opds-catalog.path opds-catalog.service /etc/systemd/system/
# Edit both files: set BOOK_DIR, BASE_URL, and User=
sudo systemctl daemon-reload
sudo systemctl enable --now opds-catalog.path

The .path unit watches the directory with inotify and triggers the service on any change.

incrond

Add to incrontab -e:

/path/to/books IN_CLOSE_WRITE,IN_CREATE,IN_DELETE,IN_MOVED_FROM,IN_MOVED_TO \
    /path/to/opds_gen.py /path/to/books --base-url https://example.com/books