NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #4063 most downloaded on PyPI
Ebook library which can handle EPUB2/EPUB3 format
Latest stable
0.21
Last release 21 days ago
01 Nov 2026
Ships fairly regularly
a new release about every 1.1 years
Most releases are documented
notes for 8 of 9 stable releases
Nothing withdrawn
no release was ever pulled
14 years old
9 releases · first in 2013
Drag across the ruler to compare, or tap a release to open it.
Update READMEmd with list of popular projects using eboolib by @Kiranpatil02 in https://github.com/aerkalov/ebooklib/pull/353
Full Changelog: https://github.com/aerkalov/ebooklib/compare/v0.20...v0.21
Your coding agent can read these notes before it upgrades. Set up the MCP server →
This is a major modernization release. It is the first release without Python 2 support and the first one with type annotations. Please read the upgrade notes before updating.
Upgrade notes
* Python 3.10 or newer is required (0.20 was the last release supporting Python 2.7 and older Python 3 versions);
lxml is now the only runtime dependency (six was removed)
* write_epub() now raises exceptions by default; the option raise_exceptions defaults to True.
Pass {"raise_exceptions": False} to keep the old behaviour of returning False
* An NCX file without navigation points is now read as book.toc == [] instead of a single blank Link
* book.uid and the written unique-identifier now follow the package unique-identifier attribute when a book
has several dc:identifier entries
* add_author() without an explicit uid now gives the second and later authors the ids creator_1, creator_2, ...
(the first one is still "creator"), so duplicate ids are no longer written
* dcterms:modified is now the UTC time (it used the local time with a Z suffix before)
* All imports from ebooklib.epub keep working; the code moved to smaller modules but everything is re-exported
Added
~~~~~
* Python 3.15 is tested in CI and listed in the package classifiers
* EpubWriter uses the mtime option as the timestamp of the files in the ZIP archive too, so writing the same book
with the same mtime gives identical files (reproducible builds) (#340)
* Tutorial: reading navigation (how the EPUB 3 nav is selected), reading order of a loaded book, item IDs,
and corrected documentation of the reader and writer options
* Add type annotations to the whole library (PEP 561 py.typed marker included), checked with ty in CI
* Add pyproject.toml (PEP 621) as the single source of packaging metadata; setup.py is now a compatibility shim
* Add typecheck job (ty) to the GitHub Actions workflow
* EpubBook.version attribute is now always defined (None for new books, set to the OPF version when reading)
Changed
~~~~~~~
* write_epub by default throws exception. Check option raise_exceptions for more details
* Drop support for Python 2.7 and Python < 3.10; minimal supported version is now Python 3.10
* Remove the six dependency; lxml is the only runtime dependency now
* Split the monolithic ebooklib/epub.py into smaller modules (consts, exceptions, toc, items, book, reader, writer);
ebooklib.epub re-exports everything, so all existing imports keep working
* Modernize code to Python 3.10+ idioms: PEP 604 unions (X | Y) in annotations and isinstance(),
typing.TypeAlias, structural pattern matching (match/case) in the manifest loader and SyntaxPlugin
* EpubItem content is now typed as accepting both str and bytes, matching long-standing documented usage
* EpubReader raises EpubException with a clear message when the OPF is missing metadata, manifest
or spine elements, or when the NCX file cannot be found (previously crashed with TypeError/AttributeError)
* EpubHtml.get_content() / EpubCoverHtml.get_content() raise a descriptive ValueError when the item
is not attached to a book (previously crashed with AttributeError)
Fixed
~~~~~
* Generate unique ids for several authors: add_author() used the id "creator" for every author, which wrote duplicate
ids into the package document (#356, #366)
* Write dcterms:modified as UTC time, as the EPUB specification requires (#367)
* The generated cover.xhtml uses an inline style on the image instead of a style element in the head, so the cover
fills the page on readers such as Kobo (#347, #352)
* Keep the identifier named by the package unique-identifier attribute when a book has several dc:identifier
entries: previously the last identifier with an id replaced it, so an ISBN listed after the main identifier became
book.uid and the written package pointed at it. When the attribute is missing or names an id that no identifier has,
the last identifier with an id is still used, as before
* Read an NCX without navigation points as an empty table of contents: book.toc is now an empty list
(previously a single blank Link, which made write_epub() fail and, being truthy, also stopped the EPUB 3 nav
document from being used as the table of contents). Code that compared book.toc with that blank Link
must check for an empty list instead. A missing navMap and a navLabel without a text child in the NCX
no longer crash the reader. See the "Reading navigation" tutorial section
* Avoid collisions with existing item IDs when assigning automatic IDs: add_item() now skips
chapter_N, image_N and static_N values that are already used (for example by a book loaded with
read_epub()) instead of creating duplicate IDs, which made get_item_with_id() return the wrong item.
Explicit IDs are still not checked for uniqueness. See the "Item IDs" tutorial section
* Preserve cover page IDs and filenames when reading the manifest
* Preserve text directly inside chapter body elements: text before the first child element of <body>
is no longer dropped by EpubHtml.get_content(), and EpubHtml.get_body_content() returns a body that
contains only text. Whitespace-only text (such as the newline and indentation before the first
element) is deliberately not copied, so the generated output of ordinary indented chapters is unchanged
and a body with only whitespace and no elements still gives an empty get_body_content()
* Return an empty list when get_metadata is called for a missing namespace
* Read EPUB 3 TOC and page-list navigation by the namespaced epub:type token list, as the EPUB
specification defines it. A multi-token value such as epub:type="toc frontmatter" is now found
(previously the TOC raised IndexError and the page list was silently lost), any namespace prefix
works, and an unrelated <nav class="toc"> menu is no longer chosen over the real table of contents.
Books without a semantic match keep the legacy lookup (any attribute exactly equal to toc/page-list);
as a new last resort a lone nav element is read as the table of contents. See the "Reading navigation"
tutorial section
* Preserve chapter bodies when Unicode XHTML includes an XML encoding declaration (#354)
* Only include elements with a pagebreak token in epub:type when automatically generating
page-list navigation; other structural semantics such as copyright-page are no longer included (#339)
* Security: prevent path traversal when reading an unpacked EPUB from a directory
(a crafted manifest href like ../../etc/passwd could read files outside the book directory);
Directory.read() raises OSError for paths escaping the source directory
* Fix possibly-unbound variables in EpubWriter guide/landmark generation; a guide entry with
a falsy item now falls back to href/title instead of reusing values from the previous entry
* Fix crash (ValueError: no path specified) when writing a book whose guide contains an entry
without href; such entries are now skipped in the EPUB3 landmarks nav
* SourceHighlighter no longer crashes on <pre class="source-..."> blocks with an unknown
language; they are left untouched instead of raising an unbound variable error
* SyntaxPlugin now preserves <form> attributes (action, method, ...); the form attribute whitelist
was previously in an unreachable duplicated details branch, so forms were stripped to global attributes
* SyntaxPlugin: remove duplicated dead branches for canvas and label tags
* TidyPlugin no longer risks a pipe deadlock on large documents (content is passed via communicate())
* EpubWriter closes the output file even when writing fails (no leaked file handles)
* XML parse errors in parse_string() are no longer masked by the str/bytes fallback path
* EpubBook.add_item() no longer writes the content encoding into media-type; mimetypes.guess_type
returns (type, encoding), and the two were swapped, so an item such as cover.svgz was declared
as media-type="gzip" in the manifest
Bug fix. Prevent None join error when HREF is not found on a link_node. by @ni-milicevic in https://github.com/aerkalov/ebooklib/pull/328
<meta> is added to the EpubHtml object by @changyy in https://github.com/aerkalov/ebooklib/pull/298Full Changelog: https://github.com/aerkalov/ebooklib/compare/v0.19...v0.20
Added
* Add Read the docs configuration file (#333)
* Add pytest support and GitHub workflow (#349)
* Add extension method for <meta> to EpubHtml object (#298)
Changed
Fixed
* Fix the version in Sphinx documentation (#335)
* Bug fix: Prevent None join error when HREF is not found on a link_node (#328)
* Fix item.get_type() does not recognize webm (#312, #338)
* Add more informative text for future Contributors (#333)
Change deprecation check by @tjkuson in https://github.com/aerkalov/ebooklib/pull/283
Full Changelog: https://github.com/aerkalov/ebooklib/compare/v0.18...v0.19
Added
* Add option to set toc page direction (#234)
* Add compresslevel parameter for zip compression (#287)
Changed
Fixed
* Throwing errors while writing EPUB is optional now and behavior will be changed in the future (#316)
* Fix lxml root warning (#305)
* Toning down metadata failure to an info log
* Check truth value of ignore_ncx deprecation, not just truthiness (#283)
* Add direction to the epub Nav page only if it was set
add direction for HTML tags by @maanijou in https://github.com/aerkalov/ebooklib/pull/174
scripted to EpubHtml properties if a script is added by @soroushj in https://github.com/aerkalov/ebooklib/pull/176Full Changelog: https://github.com/aerkalov/ebooklib/compare/v0.17.1...v0.18
Added
* Add an example for embedding images into paragraph
* Add default option ignore_ncx to EpubReader and document it (#183)
* Add option to set custom title in toc page (#243)
* Add `scripted` to EpubHtml properties if a script is added (#176)
* Read un-zipped epub directories (#183)
* Add direction for HTML tags (#174)
Changed
Fixed
* Define format for the long description
* Fix dublin core typo in tutorial documentation (#256)
* Fix EpubImage lacks parameters (#231)
* Fix the issue toc can not loaded from epub file
* Fixed #218 - Use correct variable for static item ids
* Ignore NCX if Navigation Document exists
* Try hard to parse through broken XML, improve the compatibility
Fix spelling in README.md by @tylerwhipple in https://github.com/aerkalov/ebooklib/pull/172
Full Changelog: https://github.com/aerkalov/ebooklib/compare/v0.17...v0.17.1
Added
* Initial SMIL support (#08_SMIL sample)
* Adding support for the EPUB3 pagebreak/page-list semantics
* Page lists are now attached to each EpubHtml item as well as to the book
Fixed
Fix relative path resolving by @olethanh in https://github.com/aerkalov/ebooklib/pull/122
samples/04_markdown_parse Python 2+3 compatible by @tantale in https://github.com/aerkalov/ebooklib/pull/143.gitignore by @tantale in https://github.com/aerkalov/ebooklib/pull/144Full Changelog: https://github.com/aerkalov/ebooklib/compare/v0.16...v0.17
Added
* Add WAI-ARIA role to the nav element for accessibility
* Add ability to include playOrder into navPoint (#146)
* Add get_type method to EpubCover class (#147)
Changed
.gitignore (#144)samples/04_markdown_parse Python 2+3 compatible (#143)Fixed
* Fixed #161 - Provide default value for metadata
* Fixed #159 - Add doc-toc role programmatically for EPUB accessibility
* Fixed #137 - Create a PyPi compatible README.md file
* Fixed #139 - Correct MANIFEST.in file and rename CHANGES.TXT to CHANGES.txt
* Fixed #132 - Read the README.md file using utf-8 encoding
* Fixed #125 - Refactor writing of OPF file
* Fixed #123 - Remove unused test files
* Fixed #121 - Fix relative path resolving
* Don't cut off first character of body in EpubHtml.get_body_content()
* Fix for pop-up footnotes in EPUB 3
Set blank title if it is None by @clach04 in https://github.com/aerkalov/ebooklib/pull/94
Full Changelog: https://github.com/aerkalov/ebooklib/compare/v0.15...v0.16
Added
* Add ability to set custom prefixes and namespaces to content.opf file
* Add bindings support (#70)
Changed
Fixed
* Fixed #119 - Plugin samples file uses obsolete API
* Fixed #112 - Get body content calls get content for no reason
* Fixed #111 - Initialize mimetype library only when it is being used
* Fixed #110 - Add .ttf extension to the list of font files
* Fixed #109 - spine: text orientation attribute
* Fixed #101 - Update list of authors
* Fixed #100 - Fix docstrings
* Fixed #99 - Change README.md to have ASCII encoding
* Fixed #98 - Underline tag gets deleted
* Fixed #97 - Sections are not pointing to any specific content
* Fixed #92 - set.cover not working in Python 3.4
* Fixed #85 - Epub2 guide types do not map completely to epub3 landmark types
* Fixed #84 - Set unique metadata function
* Fixed #83 - In the sample file read cover image in binary mode
* Fixed #82 - Ignore vim swapfiles
* Fixed #81 - Mimetypes library isn't aware of xhtml
* Fixed #72 - example for reading epub didn't work, wrong module level for ITEM_IMAGE
* Fixed #71 - Handling sections with content
* Fixed #69 - Correct rendition URL in OPF file
* Fixed #64 - embed <script> instead of <link> for javascripts
* Fixed #61 - Various fixes
* Fixed #36 - Implement API to add files which are not present in the manifest
* Missed doctype in the nav.xhtml file
* Removing some junk code left by git
* Remove trailing whitespace
* Tidy the code a bit
* Set blank title if it is None
* Ensure only new modified date is included
* Use relative paths in toc nav
* Allow overriding modification time for ePub document
Full Changelog: https://github.com/aerkalov/ebooklib/compare/v0.10...v0.15
Full Changelog: https://github.com/aerkalov/ebooklib/compare/v0.10...v0.15
Added
* Add basic documentation
* Support for guide (#37)
* Plugin which cleans content with Tidy HTML (#39)
* Add additional item types for audio and video files (#26)
Changed
Fixed
* Fixed #58 - Add basic documentation
* Fixed #50 - The EPUB2 guide is loaded
* Fixed #49 - The cover image item
* Fixed #48 - Load NAV document if NCX is missing
* Fixed #47 - Create head and body elements in any case
* Fixed #46 - Just a typo
* Fixed #45 - Don't parse the metadata tag itself
* Fixed #44 - Section navigation points point to the first chapter
* Fixed #43 - Update book title and UID fields after reading the metadata
* Fixed #42 - The container XML reflects the assigned EPUB folder
* Fixed #41 - Implement document type
* Fixed #40 - We must not use .wait() for waiting Popen to end
* Fixed #39 - Plugin which cleans content with Tidy HTML
* Fixed #35 - Delete temporary directory
* Fixed #34 - Mime type is not correctly guessed when adding items
* Fixed #32 - Put parsing function in the utils module
* Fixed #30 - Basic plugin for filtering non HTML5 content
* Fixed #27 - Do not create new title tag in chapter if it already exists
* Fixed #23 - Creating EPUB files does not work in Python 3.3
* Fixed #21 - Remove dependency of itertools module
* Fixed #19 - Handle properties in manifest file when writing to epub
* Fixed #18 - Decode filenames when reading them from zip file
* Fixed #17 - Read linear flag from spine structure
* Fixed #16 - EpubCoverHtml should extend EpubHtml and use it for processing HTML
* Fixed #15 - Cover file should also extend EpubHtml class
* Fixed #14 - Navigation xhtml file should behave like other xhtml files
* Fixed #13 - Item in spine could have flag linear
* Fixed #12 - Do not use ZIP_STORED for every item in zip file
* Fixed #11 - Preserve XML declaration when creating XML files
* Fixed #10 - Implement add_item method for EpubHtml
* Fixed #9 - Check type of Item in epub
* Fixed #8 - Wrong copyright info
* Fix zip paths to use correct path separator
* Updated license info in setup.py
Nothing published for this version
One column per quarter.