ebooklib

library0.20pypypi✓ verified 24d ago

Ebooklib is a Python library designed to handle EPUB2 and EPUB3 format ebooks. It provides functionalities for reading, writing, and manipulating EPUB files, allowing developers to programmatically create or modify ebook content. The library is actively maintained, with its latest version being 0.20 and a regular release cadence.

serialization data

pip install ebooklib

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · EBOOKLIB

ebooklib

serializationpythonv0.20

Install

2.2s avg

Import

101ms

Disk

28MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.20 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.106s · 30.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.2s · import 0.096s · 31MB

28MB installed

● package 28MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

EpubBook

✓ from ebooklib import epub

Primary class for representing an EPUB book.

EpubHtml

✓ from ebooklib import epub

Represents an HTML chapter or content document within the EPUB.

read_epub

✓ from ebooklib import epub

Function to read an existing EPUB file.

write_epub

✓ from ebooklib import epub

Function to write an EpubBook object to a file.

This quickstart demonstrates how to create a basic EPUB file using Ebooklib. It covers setting book metadata, adding an HTML chapter, defining the table of contents, and writing the final EPUB to disk.

import ebooklib from ebooklib import epub # Create a new book book = epub.EpubBook() # Set metadata book.set_identifier('sample123456') book.set_title('My Awesome Book') book.set_language('en') book.add_author('John Doe') # Add chapter c1 = epub.EpubHtml(title='Intro', file_name='chap_01.xhtml', lang='en') c1.content = '<h1>Introduction</h1><p>This is an introduction.</p>' # Add a stylesheet (optional) style = 'body { font-family: Calibri,sans-serif; }' nav_css = epub.EpubItem(uid="style_nav", file_name="style/nav.css", media_type="text/css", content=style) book.add_item(nav_css) book.add_item(c1) # Define Table Of Contents book.toc = (epub.Link('chap_01.xhtml', 'Introduction', 'intro'),) # Add default NCX and Nav file book.add_item(epub.EpubNcx()) book.add_item(epub.EpubNav()) # Define spine book.spine = ['nav', c1] # Write the book epub.write_epub('my_awesome_book.epub', book, {}) print("Epub book 'my_awesome_book.epub' created successfully!")

Debug

Known issues

breakingAs of v0.20, `EpubHtml.get_body_content()` now returns bytes instead of a string. Code expecting a string will need to explicitly decode the result.

fix

If your application relies on string content, decode the returned bytes, e.g., `content.decode('utf-8')`.

affects: 0.20 and later

gotchaThe default behavior for error throwing during EPUB writing (via `write_epub`) might have changed in v0.19. Previously, certain errors might have halted the process, but now they might be suppressed or optional.

fix

Explicitly set error handling options when calling `write_epub` if you rely on strict validation or specific error reporting behavior. Consult the `write_epub` documentation for available parameters.

affects: 0.19 and later

gotchaWhile Ebooklib officially supports Python 2.7, Python 2 is end-of-life and no longer maintained. Using Ebooklib in new projects should target Python 3.6+ for security, modern features, and better compatibility with the ecosystem.

fix

Migrate new projects to Python 3.6 or newer. If maintaining legacy code, be aware of Python 2 specific issues and limitations.

affects: All versions

gotchaOlder versions (particularly `0.16` to `0.18`) had known issues with correctly resolving relative paths within EPUB content (e.g., links to images, CSS files). Incorrect relative paths can lead to broken or improperly rendered EPUBs.

fix

Ensure all internal links and resource paths are correctly defined and relative to the `file_name` of the `EpubHtml` item. Update to version `0.19` or `0.20` to benefit from path resolution fixes.

affects: 0.16 to 0.18

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'ebooklib'

The 'ebooklib' package is not installed in the Python environment you are using, or the environment is not correctly activated.

fix

Install the library using pip: `pip install ebooklib`.

AttributeError: module 'ebooklib.epub' has no attribute 'read_epub'

This usually indicates that an outdated version of ebooklib is installed, or there might be a naming conflict with a local file 'epub.py' shadowing the library's module, or an incorrect import where `epub` is not the correct reference to the submodule.

fix

Ensure you have ebooklib version 0.20 (or later compatible) installed via `pip install --upgrade ebooklib`. If the error persists, check for any local 'epub.py' files in your project directory that might be conflicting. The correct usage for reading an EPUB is `from ebooklib import epub; book = epub.read_epub('my_book.epub')`.

TypeError: a bytes-like object is required, not 'str'

This error often occurs when providing string data where binary data (bytes) is expected, particularly when setting cover images or adding content. Files read using `open('filename').read()` in Python 3 return strings by default, but binary content like images needs to be read in binary mode.

fix

Open binary files (e.g., images) in binary read mode ('rb') to ensure the content is read as bytes. For example, when setting a cover: `with open('image.jpg', 'rb') as img_file: im_content = img_file.read(); book.set_cover(file_name='image.jpg', content=im_content, create_page=True)`.

AttributeError: 'bytes' object has no attribute 'seek'

This error happens when `epub.read_epub()` is called with a raw bytes object that does not behave like a file-like object with a `seek` method. The function expects either a file path (string) or a file-like object (e.g., `io.BytesIO`) that supports seeking.

fix

If you have the EPUB content as a bytes object, wrap it in `io.BytesIO` before passing it to `read_epub`: `import io; from ebooklib import epub; epub_content_bytes = download_epub_as_bytes(); book = epub.read_epub(io.BytesIO(epub_content_bytes))`.

Upgrade

Version history

0.20latest on PyPI · released Oct 26, 2025

Audit

Dependencies

lxmlrequiredRequired for parsing and generating XML (OPF, NCX, etc.) within EPUB files.

html5librequiredUsed for parsing HTML content within EPUB files.

Agent activity

49 hits · last 30 days

node