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

Uploaded Python 3

File details

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

File metadata

  • Download URL: epub_browser-1.11.2.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.2.tar.gz
Algorithm Hash digest
SHA256 a3b2408275dabf1140d50b37f8a2c94e7558ca1f7e030664ecc6c59f2a834912
MD5 f4389808c0e8a66f57d34aeb47db4c59
BLAKE2b-256 57f831de45180cab120d876ac342f792ddf92df6e0be51048a8301700b6cb402

See more details on using hashes here.

File details

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

File metadata

  • Download URL: epub_browser-1.11.2-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.2-py3-none-any.whl
Algorithm Hash digest
SHA256 620e9b6bd3a9a88644a39fc76c448da5981a23631c6487f7f22d79fa1dd51c42
MD5 9e15c78562ee4216326b3094b9c2b50e
BLAKE2b-256 b5c703b26395929aa4f16b20b2ef517d2ab4474ee9267c191ab2d3c4552e4e6c

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

1.11.5

2 files

1.11.4

2 files

1.11.3

2 files

This release

1.11.2 This release

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