EPUB Browser

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

EPUB Browser logo

PyPI version Python versions License GitHub stars

EPUB Browser turns an EPUB collection into a polished reading library for any modern browser. Use it in two equally first-class ways: run a private library for yourself, or generate a complete static reading site and deploy it directly to Pages and other static hosts. Keep your books where you choose, read on the devices you already own, and shape the experience around your habits.

Try the demo · Install from PyPI · Report an issue

Read privately. Publish simply.

Most reading tools ask you to adapt to their library, account, and interface. EPUB Browser takes the opposite view: your collection is the center of the product.

  • Your library stays yours. Run it locally or on your own server. No account is required to start reading.
  • Your library is ready to publish. Generate a self-contained static site, then deploy it directly to Cloudflare Pages, GitHub Pages, or any static host.
  • Your reading can be personal. Choose a theme, font, font size, page-turning or scrolling, and optional custom styles.
  • Your attention stays with the book. Use pure reading mode, resume where you left off, and keep notes close to the passage that matters.

It is designed as both a dependable reading companion and a practical publishing tool: quiet when you are immersed, capable when you need to organise, annotate, or turn a collection into a shareable website.

What you can do

Build a library that feels familiar

  • Import one EPUB, a folder, or an entire Calibre library.
  • Search titles, authors, and tags — including pinyin search for Chinese metadata.
  • Read Calibre tags and descriptions directly from EPUB metadata.
  • Sort library surfaces and organise a personal bookshelf with nested groups, tags, import/export, and optional sync.
  • Keep the library current with --watch when files are added or updated.

Settle into the page

  • Switch between scrolling and page-turning reading modes.
  • Resume the last chapter and reading location.
  • Adjust font family and size, use one of several themes, or add per-book custom CSS.
  • Use continuous scroll for books with many short sections.
  • Enter pure reading mode when you want the interface to disappear.
  • Zoom images, highlight code, and use keyboard navigation.
  • Read comfortably on phones, tablets, desktops, and Kindle/Silk browsers.

Keep what you notice

  • Highlight selected text, add notes, and copy the original selected passage.
  • Choose highlight colours and manage them in Settings.
  • Store annotations locally or use a compatible cloud API; export annotations as JSON whenever you need them.

Take it where you read

  • Install the generated library as a Progressive Web App on supported browsers.
  • Run the included local server, or generate static files for Cloudflare Pages, GitHub Pages, Apache, Nginx, and similar hosts.
  • Receive refreshed reader code automatically after a normal reload.

Start reading in two minutes

Install

pip install epub-browser

Open a book or library

# One book
epub-browser path/to/book.epub

# A few books
epub-browser book1.epub book2.epub book3.epub

# Every EPUB in a folder (including a Calibre library)
epub-browser /path/to/books

EPUB Browser creates a library and opens it in your browser. By default, the local server listens on port 8000 and is available to devices on your local network.

Common workflows

Keep a local library running

Use a fixed output directory when you want generated files and bookshelf data to persist between runs:

epub-browser /path/to/books \
  --output-dir /path/to/epub-browser-library \
  --sync-dir /path/to/epub-browser-sync \
  --keep-files \
  --no-browser

Add --watch to monitor the source folder and add or update books automatically:

epub-browser /path/to/books --watch --output-dir /path/to/epub-browser-library --keep-files

Generate a static site for Pages

Use --no-server when the output will be served by your own web server or static host:

epub-browser /path/to/books \
  --output-dir /path/to/public-library \
  --no-server

Upload the contents of /path/to/public-library to your preferred static host. This is the direct deployment path for Cloudflare Pages, GitHub Pages, Apache, Nginx, and similar platforms—no application server is required.

Deploy updates without stale browser assets

Each generated library publishes its CSS, JavaScript, icons, and fonts with a content-addressed filename. Those files can be cached indefinitely because a changed file always receives a new URL. The library HTML, PWA manifest, and Service Worker remain revalidated entry points, so a regular refresh discovers the new release without asking readers to clear their browser cache.

Publish the complete generated directory in one deployment whenever your host supports it. If a CDN or reverse proxy overrides origin cache headers, configure it to revalidate index.html, sw.js, and assets/manifest.json, while allowing assets/immutable/ to use long-lived immutable caching.

Useful options

# Choose a port and do not launch a browser
epub-browser book.epub --port 8080 --no-browser

# Keep generated files after a temporary local reading session
epub-browser book.epub --keep-files

# See every available option
epub-browser --help
Option Purpose
--output-dir, -o Directory for generated library files.
--no-server Generate deployable static files without starting the local server.
--keep-files Preserve generated files after the local server stops.
--watch, -w Watch the input directory for EPUB additions and changes.
--sync-dir Directory used by the optional bookshelf sync data.
--port, -p Local server port; defaults to 8000.
--no-browser Do not open a browser automatically.

Reading controls

Need Where to find it
Change font, size, or reading mode Settings in a chapter
Add custom styles Settings → Reading → Custom styles
Turn pages Left/Right Arrow or Space; use the page controls in page-turning mode
Read continuously Settings → Reading; scrolling mode only
Focus on the book Pure in the navigation controls, or click the page centre on supported devices
Highlight, annotate, or copy Select original text in the reading area

Kindle/Silk browsers are detected automatically and receive an e-reader-friendly mode. Some browser-heavy features, such as code highlighting and the bookshelf, are intentionally reduced there.

Deploy as a static site or run continuously

The --no-server output is a complete static reading site, ready to deploy wherever static files are hosted. For a self-hosted always-on library, run the command above with a persistent output directory and supervise it with your platform's service manager.

Docker

docker run -d \
  --name epub-browser \
  -p 8080:80 \
  -v /path/to/your-books:/app/Library \
  -v /path/to/generated-library:/app/EpubBrowserFiles \
  -v /path/to/sync-data:/app/SyncData \
  epub-browser:latest

Mount paths and ownership should match the user running the container.

A note on EPUB metadata

EPUB Browser reads standard EPUB metadata, including title, author, dc:subject tags, and descriptions. For Calibre-managed libraries, edit metadata in Calibre and save the book after editing so the EPUB file itself is updated.

If a book has a broken table of contents or malformed markup, opening and reconverting it with Calibre often produces a standards-compliant EPUB that reads correctly.

Contributing

Issues, bug reports, and pull requests are welcome at dfface/epub-browser. A useful report includes the EPUB source when it can be shared, the browser/device, the reading mode, and clear 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.8

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-1.11.5.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-1.11.5-py3-none-any.whl (1.5 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: epub_browser-1.11.5.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-1.11.5.tar.gz
Algorithm Hash digest
SHA256 02819ce9f838afbe43603578e0f96d19a21275ed6e842b50615464bae27ecfbb
MD5 2a5f4ee1160cee60788de13ee2c0b961
BLAKE2b-256 19fcf240f8a9cb6fc5c3396d481d05212fa8d5b527e8f243525b3ee8ee08e06c

See more details on using hashes here.

File details

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

File metadata

  • Download URL: epub_browser-1.11.5-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-1.11.5-py3-none-any.whl
Algorithm Hash digest
SHA256 b60d86f529b171cc23be55915836bca114ae40a60d2e1f0ca7a6f4a75ffb591b
MD5 08603009c5f96c1acf40d4516a6b28d6
BLAKE2b-256 f427c92244fe7d2a453db961c57067a607ad939dc6a5d8185893f3d1cc693668

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

2.0.1

2 files

2.0.0

2 files

This release

1.11.5 This release

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