Python wrappers and CLI for EpubCheck

A command line tool and lib that wraps EpubCheck for Python.

Introduction

The original EpubCheck is the standard Java-based validation tool for EPUB maintained by DAISY Consortium on behalf of the W3C, originally developed by the IDPF.

This package provides a Python library and command line tool for convenient validation of EPUB files by wrapping the original EpubCheck 5.3.0.

• Free software: BSD 3-Clause license (same as upstream EpubCheck)

Installation

If you have Python on your system you can do the usual:

$ pip install epubcheck

You must have Python & Java installed on your system. The original Java EpubCheck command line client itself is bundled in the PyPi package.

This package is tested with Python 3.10 - 3.14 on Linux, Mac and Windows. It should also work with PyPy.

Run without installing

With uv you can run the command line tool directly, without installing it into an environment first:

$ uvx epubcheck /path/to/book.epub

uvx downloads the package into a temporary, cached environment and runs it. Any of the command line options below work the same way. To install it permanently as a standalone tool instead, use:

$ uv tool install epubcheck

Quickstart

Command line usage examples

Validate all epub files in the current directory:

$ epubcheck

Validate a single EPUB file:

$ epubcheck /path/to/book.epub

Validate all files in /epubfolder and create a detailed Excel report::

$ epubcheck /path/epubfolder --xls report.xls

Show command line help::

$ epubcheck -h

Using epubcheck as a python library

from epubcheck import EpubCheck

result = EpubCheck("/path/to/book.epub")
print(result.valid)
print(result.messages)

Documentation

https://epubcheck.readthedocs.io/en/latest/

Development

Install uv, checkout this repository and run:

uv sync

Run code formatting, coverage, and tests with:

uv run poe all

Releasing

Releases are published to PyPI by GitHub Actions when a version tag is pushed. To cut one, set version in pyproject.toml and __version__ in epubcheck/__init__.py to the new version, give that version's changelog section a release date, merge to master, and then:

git tag v5.3.0
git push origin v5.3.0

The workflow checks that the tag, both version declarations and the changelog agree, runs the full test matrix against the tagged commit, builds the artifacts and validates a sample EPUB with the built wheel, uploads to PyPI, and finally creates the GitHub release from the changelog entry. Any failing check stops the release before anything is published. Uploads use trusted publishing, so no PyPI token is stored in the repository.

Changelog

5.3.0 - 2026-08-18

• Update to epubcheck 5.3.0
• Add support for Python 3.13 and 3.14
• Remove support for Python 3.8 and 3.9
• Change license to BSD 3-Clause to match upstream EpubCheck
• Switch packaging and development workflow from Poetry to uv
• Update dependencies and CI actions
• Replace deprecated argparse.FileType and close report files and the thread pool deterministically
• Exit with a non-zero status and an error message when the given path does not exist
• Publish to PyPI from GitHub Actions with trusted publishing and signed attestations

5.1.0 - 2024-06-05

• Update to epubcheck 5.1.0
• Update dependencies
• Remove support for Python 3.6 and 3.7
• Add support for Python 3.11 and 3.12

4.2.6 - 2021-11-06

• Bump versioning to match original epubcheck version
• Modernize packaging and CI
• Fix xls and csv export
• Updated dependencies

0.4.3 - 2021-09-28

• Update the epubcheck.jar to v4.2.6
• Remove support for < Python 3.6

0.4.2 - 2019-08-07

• Update the epubcheck.jar to v4.2.2 (see: https://github.com/w3c/epubcheck/releases/tag/v4.2.2)

0.3.1 - 2016-04-20

• Added custom PY2/PY3 compat module and removed dependency on six

0.3.0 - 2016-04-10

• Add commandline support with Excel batch reporting
• Moved development status from Alpha to Beta

0.2.0 - 2016-04-03

• EpubCheck results as native python objects
• More documentation

0.1.0 - 2016-04-01

• First release on PyPI.

Authors & Contributors

• Titusz Pan - https://github.com/titusz
• Sean Quinn - https://github.com/swquinn
• Curtis Smith - https://github.com/csmithd

Credits

EpubCheck is a project coordinated by IDPF. Most of the EpubCheck functionality comes from the schema validation tool Jing and schemas that were developed by IDPF and DAISY. Initial EpubCheck development was largely done at Adobe Systems.