EPUB Browser

A personal EPUB reader and static-site generator. Read privately. Publish anywhere.

EPUB Browser logo

PyPI version Python versions License

EPUB Browser v2 has two explicit product modes:

  • ssg generates a complete static-site snapshot for Pages, object storage, Nginx, or any other static host.
  • server runs a stateful reading service with durable SQLite data, an incremental generated cache, optional file watching, and browser APIs.

Choose the mode from what you are deploying—not from whether a build step happens internally.

Install

pip install epub-browser

Python 3.9 or newer is required.

SSG: generate a static site

Generate a site for a domain root:

epub-browser ssg /path/to/books \
  --output-dir /path/to/dist

For GitHub Pages or another project subpath, set the public URL prefix explicitly:

epub-browser ssg /path/to/books \
  --output-dir /path/to/dist \
  --base-path /my-repository/

--base-path changes generated browser URLs; it does not change the output directory. For example, --base-path /my-repository/ makes links, manifests, icons, book metadata, and Service Worker entries start with /my-repository/ while files are still written directly inside dist/.

SSG activation is transactional: EPUB Browser builds and validates a sibling staging snapshot, then replaces the destination. A failed conversion leaves the previous output untouched. SSG output contains no Server database, migration state, or runtime cache metadata.

Browser-local bookshelf data remains local unless you use the existing manual Sync action against a compatible endpoint. Static reading progress and annotations stay in browser storage and do not probe EPUB Browser Server APIs.

Server: run a persistent reading library

For a private local library:

epub-browser server /path/to/books \
  --server-dir /path/to/epub-browser-state \
  --watch

Server binds to 127.0.0.1 by default. This is the safe default for one machine. To make it reachable on a trusted LAN, opt in explicitly:

epub-browser server /path/to/books \
  --server-dir /path/to/epub-browser-state \
  --watch \
  --host 0.0.0.0 \
  --port 8080 \
  --no-browser

Do not expose the built-in Server directly to the public internet. Put it behind a TLS reverse proxy with authentication and appropriate network controls.

For a disposable session, use --ephemeral instead of --server-dir:

epub-browser server book.epub --ephemeral
  • Initial and watch scans appear in the Server library page; Server mode does not use terminal tqdm.
  • Interactive terminals print the bound URL once. Docker/systemd runs stay quiet unless --log is enabled.
  • A successful scan summary closes automatically; failures remain visible until dismissed. Fixing or replacing the EPUB lets --watch start the next scan—there is no manual retry endpoint.

Server storage contract

<server-dir>/
├── .server.lock                 # reusable process-lock metadata
├── data/
│   ├── epub-browser.db          # durable books, annotations, bookshelf sync, progress
│   ├── migration-state.json     # restart-safe v2 migration state
│   └── backups/                 # verified pre-migration database copies
└── cache/
    ├── catalog.json             # generated-cache status
    ├── public/                  # served HTML, assets, and converted books
    └── staging/                 # replaceable conversion work

Only data/ is authoritative. cache/ can be deleted: the next start rebuilds it while retaining durable book IDs and user data. .server.lock remains as harmless diagnostic metadata after shutdown; an operating-system lock, rather than its recorded PID, controls exclusivity. Public files are never written at the Server root in the v2 layout.

The bookshelf continues to use browser-local state and the existing manual Sync action. Therefore an untouched Server database can legitimately have no bookshelf row until a user performs Sync. This behavior is unchanged in v2.

Docker

The image runs persistent Server mode. Mount EPUB input read-only and Server state read-write:

docker run -d \
  --name epub-browser \
  -p 127.0.0.1:8080:80 \
  -v /path/to/books:/app/Library:ro \
  -v /path/to/epub-browser-state:/app/EpubBrowserFiles \
  epub-browser:2.0.1

/app/EpubBrowserFiles must be writable and persistent. /app/Library is read-only input. Mount /app/SyncData:ro only when legacy bookshelf JSON needs to be imported:

-v /path/to/legacy-sync:/app/SyncData:ro

The container intentionally binds the process to 0.0.0.0; control exposure with the published Docker port, firewall, and reverse proxy.

Legacy v1 command compatibility

v2 accepts the v1 syntax for the full v2 major line and maps it to one of the new modes:

v1 command shape v2 equivalent
epub-browser BOOKS epub-browser server BOOKS --ephemeral
epub-browser BOOKS --output-dir STATE epub-browser server BOOKS --server-dir STATE
epub-browser BOOKS --no-server --output-dir DIST epub-browser ssg BOOKS --output-dir DIST
--sync-dir DIR server --legacy-sync-dir DIR

With --log, legacy invocation prints the equivalent v2 command. Without --log, the adapter stays quiet. Legacy temporary --keep-files is retained; persistent Server directories are already permanent.

See Migrating to v2 for backup, automatic data migration, conflict recovery, and rollback details.

Useful options

epub-browser ssg --help
epub-browser server --help
Mode Option Purpose
SSG --output-dir, -o Required static snapshot destination.
SSG --base-path Public URL prefix, default /.
Server --server-dir Persistent data and cache root.
Server --ephemeral Disposable Server root; mutually exclusive with --server-dir.
Server --watch, -w Reconcile source changes automatically.
Server --host Bind address, default 127.0.0.1.
Server --port, -p Bind port, default 8000.
Server --legacy-sync-dir Read legacy bookshelf JSON during migration.
Both --log Show operational detail without corrupting progress output.

Reading features

  • Recursive EPUB and Calibre-library discovery, metadata tags, search, and pinyin search.
  • Scrolling, page turning, continuous reading, custom fonts and CSS, themes, and pure reading mode.
  • Highlights and notes with browser or Server-backed annotation storage where available.
  • Nested bookshelf groups, tags, JSON import/export, and the existing optional manual sync.
  • PWA manifests and content-addressed static assets.
  • English and Simplified Chinese browser UI.

Kindle/Silk browsers receive an e-reader-friendly mode; browser-heavy features may be reduced.

Data safety and migration

Persistent Server startup automatically checks for the v1 root database, verifies it, creates a backup, upgrades a copied database, imports eligible legacy bookshelf JSON, and only then removes the migrated root database. Legacy public files are retired in two successful startup phases and are never treated as authoritative data.

If both epub-browser.db and annotations.db exist at the legacy root, startup stops with a conflict instead of guessing. Corrupt databases are also left untouched. See docs/migration-v2.md.

Contributing

Issues and pull requests are welcome at dfface/epub-browser. A useful report includes the EPUB when it can be shared, the exact command, browser/device, and reproduction steps.

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.1.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dfface from gravatar.com dfface

Credits

Author: dfface

License

MIT

Requires

Python >=3.9

Tags

epub reader html export browser convert calibre-web calibre kindle web server local

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

epub_browser-2.0.1.tar.gz (1.5 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

epub_browser-2.0.1-py3-none-any.whl (1.5 MB view details)

Uploaded Python 3

File details

Details for the file epub_browser-2.0.1.tar.gz.

File metadata

  • Download URL: epub_browser-2.0.1.tar.gz
  • Upload date:
  • Size: 1.5 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.14.7

File hashes

Hashes for epub_browser-2.0.1.tar.gz
Algorithm Hash digest
SHA256 c74ac92a9006192f45b02789310c87e943f0352f5691cabecb644c56df160a80
MD5 0416d533365108760ac3f4396c02841c
BLAKE2b-256 139feaa6f4110aea4466ec7d0cedc6e415f5b8a94ad77bf5a23b7501a7d9d2ac

See more details on using hashes here.

File details

Details for the file epub_browser-2.0.1-py3-none-any.whl.

File metadata

  • Download URL: epub_browser-2.0.1-py3-none-any.whl
  • Upload date:
  • Size: 1.5 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.14.7

File hashes

Hashes for epub_browser-2.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 82fdca398c96f18444c64b951dddf8bf48d084e135d014b86b8a0e93b6d3ab6a
MD5 7b5fac09e5f4fdaf085b07b3fe6b889f
BLAKE2b-256 6cc3557ae71a4e71fdf8fb0e6b627b3ec4d66b5885d246e95e22a784d3499018

See more details on using hashes here.

Release history Release notifications | RSS feed

2.1.1

2 files

2.1.0

2 files

2.0.5

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

This release

2.0.1 This release

2 files

2.0.0

2 files

1.11.5

2 files

1.11.4

2 files

1.11.3

2 files

1.11.2

2 files

1.11.1

2 files

1.11.0

2 files

1.10.9

2 files

1.10.8

2 files

1.10.7

2 files

1.10.6

2 files

1.10.5

2 files

1.10.4

2 files

1.10.3

2 files

1.10.2

2 files

1.10.1

2 files

1.10.0

2 files

1.9.4

2 files

1.9.3

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.13

2 files

1.8.12

2 files

1.8.11

2 files

1.8.10

2 files

1.8.9

2 files

1.8.7

2 files

1.8.6

2 files

1.8.5

2 files

1.8.4

2 files

1.8.3

2 files

1.8.2

2 files

1.8.1

2 files

1.8.0

2 files

1.7.16

2 files

1.7.15

2 files

1.7.14

2 files

1.7.13

2 files

1.7.12

2 files

1.7.11

2 files

1.7.10

2 files

1.7.9

2 files

1.7.8

2 files

1.7.7

2 files

1.7.6

2 files

1.7.5

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.19

2 files

1.6.18

2 files

1.6.17

2 files

Yanked

1.6.16

2 files

1.6.15

2 files

1.6.14

2 files

1.6.13

2 files

1.6.12

2 files

1.6.11

2 files

1.6.9

2 files

1.6.8

2 files

1.6.7

2 files

1.6.6

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

Yanked

1.5.0

2 files

Yanked reason: can not use

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

Yanked

1.4.0

2 files

Yanked reason: can not use

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.1

2 files

1.3.0

2 files

1.2.12

2 files

1.2.11

2 files

1.2.10

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

Yanked

1.2.0

2 files

Yanked reason: can not use

1.1.7

2 files

1.1.6

2 files

1.1.5

2 files

1.1.4

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

1 file

0.6.0

1 file

0.5.0

2 files

0.4.0

2 files

0.3.0

2 files

0.2.0

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page