EbookLib Changelog

All notable changes to this project will be documented in this file.


Version 0.21 (2026-11-01)
-------------------------

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


Version 0.20 (2025-10-26)
------------------

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
~~~~~~~
* Reformat all code with ruff, fix docs
* Update the list of software using ebooklib
* Increase the priority of inserting <meta> into <head>
* Return bytes in EpubHtml's content getter methods (#319)

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)


Version 0.19 (2025-05-02)
-------------------------

Added
~~~~~
* Add option to set toc page direction (#234)
* Add compresslevel parameter for zip compression (#287)

Changed
~~~~~~~
* Update README.md with refreshing the project issue
* Use posix module instead of os.path when managing EPUB references (#305)
* Change deprecation check for ignore_ncx
* Using lxml text_content() on all nodes for better ToC parsing

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


Version 0.18 (2022-11-30)
-------------------------

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
~~~~~~~
* Update AUTHORS.txt file
* Improved header in README.md
* Updated README.md; Added python linting, updated file links
* Use custom XMLParser for security
* Use double quotes for XML declaration in xml container

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


Version 0.17.1 (2019-01-03)
---------------------------

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
~~~~~
* Increase version number to 0.17.1
* Update README.md
* Update AUTHORS.txt file
* Fixed #168 - Improve Sphinx documentation a bit
* Fixed #166 - Readfile method fails on MS Windows
* Fixed #165 - Sample file 05_plugins_create files on Python 3+
* Fixed #164 - Parsing files fails because of page-list
* Fixed #163 - epub:type is not properly extracted


Version 0.17 (2018-07-04)
-------------------------

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
~~~~~~~
* Improve playOrder logic to handle subchapters correctly (#148)
* Improved `.gitignore` (#144)
* Make `samples/04_markdown_parse` Python 2+3 compatible (#143)
* Dynamically change the long-description in project configuration
* Change double quotes into single quotes

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


Version 0.16 (2017-04-03)
-------------------------

Added
~~~~~
* Add ability to set custom prefixes and namespaces to content.opf file
* Add bindings support (#70)

Changed
~~~~~~~
* Remove Booktype version number
* Reconstruct options for legacy tidy
* Control attribute order of meta tag
* Update Readme with new project that uses ebooklib

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


Version 0.15 (2014-05-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
~~~~~~~
* Implement new API for Plugins (#33)
* Move common functions to ebooklib.utils (#29)
* Use six package for Python2/Python3 compatibility (#28)
* Implement different methods for fetching different items from a book (#25)
* Make some function names more pythonic + update docs + update examples (#24)
* Make it work on Python 2.7 / Python 3.3 (#22)
* Update README file

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


Version 0.10 (2013-05-07)
-------------------------

* Initial public release
* Basic EPUB2/EPUB3 read and write support
* Plugin system for content manipulation
* Fixed #6 - Fix typo in setup.py
* Fixed #5 - Remove print statements from source code
* Fixed #4 - Fix error in README file
* Fixed #3 - Add sample files
* Fixed #2 - Update README file with code samples
* Fixed #1 - Add copyright, author info and setup.py
