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.10.2.tar.gz (1.4 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.10.2-py3-none-any.whl (1.4 MB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: epub_browser-1.10.2.tar.gz
  • Upload date:
  • Size: 1.4 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.10.2.tar.gz
Algorithm Hash digest
SHA256 ea899673086134d8700992ebbf2330aad3047ded09d24ef0483f2cf59e6af1a0
MD5 ed816a008753a080d2f8f81b5acaed57
BLAKE2b-256 b094bc02a7b04af5225a3e92dd823e40791d56f6fbfe6bfc64c507d7f0cc8686

See more details on using hashes here.

File details

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

File metadata

  • Download URL: epub_browser-1.10.2-py3-none-any.whl
  • Upload date:
  • Size: 1.4 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.10.2-py3-none-any.whl
Algorithm Hash digest
SHA256 0d3c864fbcc36c16d30e87440558182c7b515c94fc629b7b51548a3d39124063
MD5 e44c94a12ff5ee67bff86830bb20296e
BLAKE2b-256 c2a677f342617a208acc29a443e2212034ec78d90bada5bcb61f5989829fa11d

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

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

This release

1.10.2 This release

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