EPUBCheck for validating EPUB 2 and EPUB 3 publications

What EPUBCheck validates

EPUBCheck solves a narrow but consequential publishing problem: determining whether an EPUB publication conforms to the EPUB specifications. The README identifies it as the official conformance checker for EPUB publications and says that it can validate both EPUB 2 and EPUB 3 files. That makes it relevant to publishers, ebook production teams, conversion vendors, localization workflows, and developers building publication tooling. It is also useful as a repeatable gate before a book is delivered to a distribution platform.

The current production release named in the README is EPUBCheck v5.4.0, released on 2026-09-15. It checks EPUB 3 publications against the EPUB 3.4 specification. The earlier releases listed in the repository include v5.3.0 from 2025-09-01 and v5.2.1 from 2025-01-14. The README does not claim that a passing result guarantees that a publication will render identically in every reading system, nor does it document checks for commercial platform policies that are outside the EPUB specifications.

EPUBCheck should therefore be treated as a standards validation stage. It can identify conformance problems in a publication, but it cannot decide whether prose is well edited, whether cover art is visually effective, or whether metadata is commercially suitable. Those are separate production concerns. A clean result is evidence about specification conformance, not a complete publication approval.

The validation path and Java integration

The project exposes two documented operating modes: a standalone command-line tool and a Java library. The repository's Dockerfile shows that the distribution is built around an executable JAR at `/app/epubcheck.jar`, with supporting libraries copied into `/app/lib`. Its generated entry point invokes the JAR with `java -jar /app/epubcheck.jar "$@"`, passing command-line arguments through unchanged. This is a conventional Java execution model rather than a hosted service.

The README credits Jing as a significant source of functionality, specifically schema validation. It also credits schemas from the Nu HTML Checker, IDPF, and DAISY. Based on that description, EPUBCheck combines EPUB-specific validation behavior with schema checking. The README does not provide the complete validation pipeline, message taxonomy, or Java API surface, so those details should be checked in the project wiki or source before designing an integration around a particular error class.

For Java users, the library form allows validation code to be embedded in a larger publishing service or build process. The README does not document Maven coordinates, public class names, callback interfaces, or exception types. It does document that contributors and technical discussions exist through the project wiki, public mailing list, and contribution files. In particular, `CONTRIBUTING.md` is present at the repository root, while the README points to the EPUBCheck wiki for contribution instructions and message translation work.

This architecture is practical when a pipeline already uses Java and needs one validation component without launching a separate process. It also means that integration requires more than adding a command to a shell script: API compatibility and message handling must be verified against the chosen release.

Building EPUBCheck from source with Maven

The README lists the source-build requirements as JDK 1.7 or above and Apache Maven 3.0 or above. The documented build command runs the Maven lifecycle and copies JAR files and packages into the `target/` directory. This is the appropriate starting point for contributors or teams that need to build the project themselves.

The build command is:

$ mvn clean install

The README states that this command builds the project and runs its tests. The resulting artifacts are placed under `target/`. The README does not specify the exact Maven profile, test dependencies, or the names of all generated files beyond the `*.jar` pattern, so those details should not be assumed.

The Dockerfile gives a separate, more concrete container path. It builds with `maven:3-eclipse-temurin-25-alpine`, runs `mvn clean install -DskipTests`, and then copies `/app/target/epubcheck.jar` and `/app/target/lib` into an `eclipse-temurin:25-jre-alpine` runtime image. The container therefore presents a different Java runtime from the README's stated minimum source-build environment. That difference matters for teams choosing between a local Maven build and the Docker workflow.

For a first local build, install the required JDK and Maven, clone the repository, and run the command from the project root. Inspect `target/` for the generated artifacts. Before adopting the build in CI, compare the local toolchain with the container's Java 25 setup and decide whether the application being built is meant to mirror the container or support the broader JDK range documented in the README.

Running validation locally and in Docker

The repository documents Docker as a complete execution example because the image includes the checker JAR, its library directory, and an entry point. The host EPUB and any generated reports must be mounted under `/data`, which is the container's working directory and declared volume.

Build the image with:

$ docker build . -t epubcheck

The README uses `<directory>` as a placeholder for a host path. A command that validates a file in the current directory is:

$ docker run -it --rm -v .:/data epubcheck sample.epub

The file is read from the mounted `/data` directory, and the README says that validation results are printed to the console. For a file stored elsewhere, mount that directory instead:

$ docker run -it --rm -v /home/username:/data epubcheck sample.epub

To write a JSON report, pass `--json` and an output path inside the mounted directory:

$ docker run -it --rm -v .:/data epubcheck sample.epub --json output.json

The README states that `output.json` is generated at `/data/output.json` in the container and appears in the corresponding host directory. The `Dockerfile` sets `DATA_PATH=/data`, uses `/data` as its working directory, declares it as a volume, and forwards all arguments to the JAR. This design makes host permissions and mount paths important operational details. A successful Docker launch still requires the EPUB file to exist at the mounted location and the output directory to be writable.

Where EPUBCheck stops and Jing becomes relevant

EPUBCheck is the appropriate choice when the required decision is EPUB conformance. It is a purpose-built checker maintained by the DAISY Consortium on behalf of W3C, and the repository includes EPUB-focused schemas and validation behavior. Its output is intended to support publication production and compliance checks.

A real alternative approach is to depend on a general schema validator such as Jing directly, with an independently selected set of EPUB-related schemas. That approach differs in scope. Jing provides schema validation, while EPUBCheck adds the EPUB-specific rules, supported EPUB versions, message handling, packaging behavior, and command-line distribution described by the project. The README explicitly says that a significant part of EPUBCheck functionality comes from Jing, so the tools are related rather than unrelated products.

Choosing Jing alone could make sense for an engineering team that already controls the exact schemas and has its own EPUB packaging rules. It also transfers responsibility for maintaining that ruleset. Choosing EPUBCheck avoids assembling the schema and validation layers yourself, but keeps the project in Java and ties upgrade decisions to EPUBCheck releases. The README does not provide a direct feature matrix against Jing, so teams should not infer equivalent coverage merely from the shared validation component.

EPUBCheck is the wrong tool for judging accessibility beyond what its documented EPUB checks enforce, editorial quality, reader-system compatibility, or platform-specific commercial requirements. It is also not a replacement for opening the publication in target reading systems.

Maintenance, upgrades, and the BSD-3-Clause license

The repository is not archived. Its last push was on 2026-10-08, so the project has a recent recorded update. The README identifies the DAISY Consortium as the current maintainer on behalf of W3C. That does not mean every organization using EPUBCheck can ignore upgrade planning. A new release can change the specification revision used for validation, add or correct messages, and alter the behavior expected by a publishing pipeline.

The release sequence shows that upgrades are part of the project's normal path: v5.4.0 followed v5.3.0 and v5.2.1. Teams that validate EPUB 3.4 files should record the exact EPUBCheck version used for each publication or release candidate. Otherwise, a changed result can be difficult to interpret when a validator is upgraded. The README does not document a compatibility policy, a long-term support schedule, or a rollback procedure, so those points require confirmation from the maintainers or project documentation before they become operational assumptions.

The repository license is BSD-3-Clause. That identifier indicates the license declared by the project, but this review does not provide legal interpretation. Anyone embedding the JAR, redistributing a modified build, or shipping the Docker image should review the repository's `LICENSE.md` and account for the actual distribution context. The source build and container image also have separate maintenance surfaces: Maven and the JDK for a local build, Docker and the selected base images for the container workflow.

Editorial conclusion

EPUBCheck is appropriate for publishers, conversion pipelines, QA teams, and developers that need standards-focused EPUB validation from a CLI or Java integration. It is not a replacement for an EPUB reader, authoring application, or workflow-specific editorial review. Verify first that your target publication is covered by the selected release, especially if it depends on a specification newer than EPUB 3.4, and confirm that the build or distribution matches your Java environment.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. w3c/epubcheck on GitHub