Ebooklib

0.20 · active · verified Sun Apr 12

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.

Warnings

breaking As 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')`.
gotcha The 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.
gotcha While 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.
gotcha Older 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.

Install

pip install ebooklib Install Ebooklib

Imports

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.

Quickstart

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!")

view raw JSON →