epub-browser

A modern web-based EPUB reader with library management, dark mode, Kindle optimization, code highlighting, and PWA support for an enhanced reading experience across devices.

It functions as a static site generator, and the generated static files can be deployed to Cloudflare Pages, GitHub Pages, and other platforms.

Try it online: https://epub-browser-test.yuhan.tech

It now supports the following features:

• Basic library management: Search by title, author or tag. Supports pinyin search for Chinese titles and authors (e.g., searching "santi" will match "三体").

• Theme system (disabled in Kindle Mode): Multiple themes supported including light, dark, sepia, forest, ocean, peach, and lavender. Theme selection is available in the top right corner.

• Page navigation: Keyboard controls supported (Left Arrow, Right Arrow and Spacebar for page turning/scrolling).

• Kindle Mode: Enhanced style optimizations; allows page turning by tapping either side of the screen. Automatically detected based on device user agent (Kindle/Silk browsers).

• Reading progress bar

• Chapter-wise table of contents.

• Font size and font family adjustment

• Image zoom functionality

• Mobile device compatibility: Fully optimized for mobile devices including Kindle e-readers. Kindle Mode is automatically detected and enabled for Kindle/Silk browsers.

• Code highlighting (disabled in Kindle Mode) with theme synchronization.

• Reading position retention: Restores your last-read chapter (supported on all devices including Kindle) and your last-read location (supported on all devices except Kindle).

• Custom CSS: Tailor the reading experience with custom styles, e.g.

  #eb-content { margin: 50px; }
  #eb-content p { font-size: 2rem; }

  Note: All core content is nested under the element with the #eb-content selector.

• Direct deployment on any web server (e.g. Apache): Use the --no-server parameter.

• Multithreading support

• Drag-and-drop sorting: Main interface elements are draggable.

• Calibre metadata integration: Displays tags (dc:subject) and comments (dc:description) edited in Calibre. Note: After editing metadata in Calibre, use the "Edit book" function to save your changes.

• Watchdog utility: Monitors the user-specified directory (or the directory containing EPUB files) with --watch parameter. Automatically adds newly added or updated EPUB files to the library.

• Progressive Web App (PWA): Installable as a native app on supported devices for a more app-like experience.

• Pure Reading Mode: Hides all toolbars for distraction-free reading. On desktop, toggle via the "Pure" button in the navigation bar or by clicking the center of the screen. On mobile, toggle by clicking the center of the screen.

• Cache management: Update button in library to clear Service Worker cache and refresh content.

• Bookshelf: Personal bookshelf with grouping support (non-Kindle mode only). Features include:

  • Add/remove books to shelf from book detail page
  • Create nested groups for organization
  • Tag-based filtering within shelf and groups
  • Drag-and-drop sorting for books and groups
  • Export/import shelf data as JSON (supports both file upload and URL import)
  • Statistics showing book and group counts
  • Sync: Synchronize shelf data across devices using a username. The sync feature uses version control to manage data changes and supports conflict resolution.

Usage

Type the command in the terminal:

pip install epub-browser

# Open single book
epub-browser path/to/book1.epub

# Open multiple books
epub-browser book1.epub book2.epub book3.epub

# Open multiple books under the path
epub-browser *.epub

# Open multiple books under the current path
epub-browser .

# Do not start the server; only generate static website files, which can be directly deployed on any web server such as Apache.
epub-browser . --no-server

# Monitor all EPUB files in the directory specified by the user (or the directory where the EPUB file resides). When there are new additions or updates, automatically add them to the library.
epub-browser . --watch

# Specify the output directory of html files, or use tmp directory by default
epub-browser book1.epub book2.epub --output-dir /path/to/output

# Save the converted html files, will not clean the target tmp directory;
# Note: These files are for inspection purposes only and cannot be directly deployed to a web server. To enable direct deployment, please use the --no-server parameter.
epub-browser book1.epub --keep-files

# Do not open the browser automatically
epub-browser book1.epub book2.epub --no-browser

# Specify the server port
epub-browser book1.epub --port 8080

# Specify the sync directory for bookshelf data (default: same as output directory)
epub-browser book1.epub --sync-dir /path/to/sync-data

Then a browser will be opened to view the epub file.

For more usage information, please use the --help parameter.

➜ epub-browser --help                                                                                        
usage: epub-browser [-h] [--port PORT] [--no-browser] [--output-dir OUTPUT_DIR] [--keep-files] [--log] [--no-server] [--watch] [--sync-dir SYNC_DIR]
                    filename [filename ...]

EPUB to Web Converter - Multi-book Support

positional arguments:
  filename              EPUB file path(s)

options:
  -h, --help            show this help message and exit
  --port, -p PORT       Web server port (default: 8000)
  --no-browser          Do not automatically open browser
  --output-dir, -o OUTPUT_DIR
                        Output directory for converted books
  --keep-files          Keep converted files after server stops. To enable direct deployment, please use the --no-server parameter.
  --log                 Enable log messages
  --no-server           Do not start a server, just generate files which can be directly deployed on any web server such as Apache.
  --watch, -w           Monitor all EPUB files in the directory specified by the user (or the directory where the EPUB file resides).
                        When there are new additions or updates, automatically add them to the library.
  --sync-dir SYNC_DIR   Directory to store bookshelf sync data (default: same as current work directory)

Startup

How do I set it to start automatically on boot?

macOS

1. add a file epub-browser.plist in ~/Library/LaunchAgents:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
    <dict>
        <key>Label</key>
        <string>Epub-Browser</string>
        <key>ProgramArguments</key>
        <array>
            <string>/path/to/.venv/bin/epub-browser</string>
            <string>--output-dir</string>
            <string>/path/to/workdir</string>
            <string>--watch</string>
            <string>--no-browser</string>
            <string>--keep-files</string>
            <string>/path/to/Calibre Library</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>WorkingDirectory</key>
        <string>/path/to/workdir</string>
        <key>StandardOutPath</key>
        <string>/path/to/workdir/run.log</string>
        <key>StandardErrorPath</key>
        <string>/path/to/workdir/err.log</string>
    </dict>
</plist>

run which epub-browser to get the full path of epub-browser

1. run the command to make effective:

launchctl load -w ~/Library/LaunchAgents/epub-browser.plist
# launchctl unload -w ~/Library/LaunchAgents/epub-browser.plist
launchctl start epub-browser
# using kickstart to restart like this:
# launchctl kickstart -k gui/501/Epub-Browser 

Linux

wait someone to add or ask ChatGPT.

Docker

Start the service using docker-compose up -d:

version: "3"
services:
  epub-browser:
    image: dfface/epub-browser:latest
    user: 1000:1000 # should be owner of volumes
    restart: unless-stopped
    ports:
      - "8088:80"
    volumes:
      - "/Users/dfface/Calibre Library:/app/Library/Calibre"
      - "/Users/dfface/xxx Book Library:/app/Library/xxxBook"
      - "/Users/dfface/data/epub-browser/tmp-files:/app/EpubBrowserFiles"
      - "/Users/dfface/data/epub-browser/sync-data:/app/SyncData"

or just with docker:

docker run -d \
  --name epub-browser-service \
  -p 8080:80 \
  -v /path/to/YourEpubDir:/app/Library \
  -v /path/to/EpubBrowserTmpFiles:/app/EpubBrowserFiles \
  -v /path/to/EpubBrowserSyncData:/app/SyncData \
  epub-browser:latest

Tips

• If there are errors or some mistakes in epub files, then you can use Calibre to convert to epub again.
  • Issue: EPUB table of contents fails to display properly, usually due to missing toc.ncx file.
  • Fix: Use Calibre to re-convert the original file to EPUB. This generates a specification-compliant EPUB with correct TOC display.
• Tags can be managed by calibre. After adding tags, you should click "Edit book" and just close the window to update the epub file or the tags will not change in the browser.
• By default, the program listens on the address 0.0.0.0. This means you can access the service via any of your local machine's addresses (such as a local area network (LAN) address like 192.168.1.233), not just localhost.
• Just find calibre library and run epub-browser ., it will collect all books that managed by calibre.
• You can combine web reading with the web extension called Circle Reader to gain more elegant experience.Other extensions that are recommended are: Diigo: Read more effectively with annotation tools ...