Skip to content

Running

Jump to bottom
Daniel Weck edited this page Aug 5, 2019 · 17 revisions

EPUBCheck is a command line tool, all detected errors are simply printed to stderr output stream.

There's no native GUI – however, there are some thirdparty apps offering a GUI. See the GUI wiki page for further details.

System prerequisites

To run the tool you need Java (1.6 or above, 1.7+ recommended). Any Operating System should do.

Note on Java:

You need at least JRE or JDK 1.6 to run EPUBCheck on the commandline. However, starting with EPUBCheck 4.0 we recommend Java 1.7 or 1.8 to be able to run advanced image checks (Java 1.6 doesn't support those).

Note on Java on Mac OS X:

Due to the change in ownership of the Apple Java version from Apple to Oracle, Java 1.6 (Apple) and Java 1.7+ (Oracle) are kind of incompatible to each other. To run EPUBCheck with advanced image checks in a Mac OS X Terminal, the Oracle JDK 1.7, 1.8, 9 or 10 or Open JDK 11+ is required!

Running from the command line

Overview of commandline arguments

Print the commandline help with the --help argument:

$ java -jar epubcheck.jar --help

EPUBCheck v4.0.2

When running this tool, the first argument should be the name (with the path)
of the file to check.

To specify a validation profile (to run checks against a specific EPUB 3 profile
or extension specification), use the -profile option:

Validation profiles supported:
--profile default // the default validation profile
--profile dict    // validates against the EPUB Dictionaries and Glossaries specification
--profile edupub  // validates against the EDUPUB Profile
--profile idx     // validates against the EPUB Indexes specification
--profile preview // validates against the EPUB Previews specification

If checking a non-epub file, the epub version of the file must
be specified using -v and the type of the file using -mode.
The default version is: 3.0.

Modes and versions supported: 
--mode opf -v 2.0
--mode opf -v 3.0
--mode xhtml -v 2.0
--mode xhtml -v 3.0
--mode svg -v 2.0
--mode svg -v 3.0
--mode nav -v 3.0
--mode mo  -v 3.0 // For Media Overlays validation
--mode exp  // For expanded EPUB archives

This tool also accepts the following options:
--save 	       = saves the epub created from the expanded epub
--out <file>     = output an assessment XML document file (use - to output to console)
--xmp <file>     = output an assessment XMP document file (use - to output to console)
--json <file>    = output an assessment JSON document file (use - to output to console)
-m <file>        = same as --mode
-p <profile>     = same as --profile
-o <file>        = same as --out
-x <file>        = same as --xmp
-j <file>        = same as --json
--failonwarnings[+|-] = By default, the tool returns a 1 if errors are found in the file or 0 if no errors
                        are found.  Using --failonwarnings will cause the process to exit with a status of
                        1 if either warnings or errors are present and 0 only when there are no errors or warnings.
-q, --quiet      = no message on console, except errors, only in the output
-f, --fatal      = include only fatal errors in the output
-e, --error      = include only error and fatal severity messages in ouput
-w, --warn       = include fatal, error, and warn severity messages in output
-u, --usage      = include ePub feature usage information in output
                    (default is OFF); if enabled, usage information will
                    always be included in the output file

-l, --listChecks [<file>] = list message ids and severity levels to the custom message file named <file>
                          or the console
-c, --customMessages [<file>] = override message severity levels as defined in the custom message file named <file>

-h, -? or --help = displays this help message

No file specified in the arguments. Exiting.
epubcheck completed

Validating a packaged EPUB

java -jar epubcheck.jar file.epub

Specifying a validation profile

It is possible to specify a validation profile to validate an EPUB (or single file thereof) against a specific IDPF specification.

java -jar epubcheck.jar file.epub -profile PROFILE

Current profiles include:

Note: In most cases, it is not required to specify the validation profile explicitly, as it will automatically be set according to dc:type metadata in the Publication. Setting the profile explicitly can be useful to detect when such dc:type metadata is missing, or to validate single files (see next section).

Validating a single file

java -jar epubcheck.jar singleFile -mode MODE -v VERSION -profile PROFILE

  • MODE must be one of the following:

  • opf for package document validation;

  • nav for navigation document validation (available only for version 3.0);

  • mo for media overlay validation (available only for version 3.0);

  • xhtml;

  • svg;

  • exp for Expanded EPUB validation (see the next section)

  • VERSION must be one of

  • 2.0

  • 3.0

  • PROFILE is optional (see the previous section).

Note that when validating a single file, only a subset of the available tests is run. Also, when validating a full EPUB, both mode and version are ignored.

Validating an "expanded" (i.e. unzipped) EPUB

java -jar epubcheck.jar folder/ -mode exp [-save]

When using expanded mode, there's an optional flag -save to save the created archive upon validation.

Additional flags

  • -out file.xml outputs an assessment XML document
  • -quiet or -q outputs only if there is any warning or error
  • -help, --help or -? displays a help message

Troubleshooting

File not found error

If EPUBCheck fails because of Unicode characters in file paths, the following command line parameters can be used:

java -Dsun.jnu.encoding=UTF8 -Dfile.encoding=UTF8 -jar epubcheck.jar "Mały Książę - Antoine de Saint-Exupéry.epub"

("Mały Książę" = "Le Petit Prince" in Polish)

java.lang.StackOverflowError

If EPUBCheck crashes with a StackOverflowError, try adjusting the thread stack size of your Java Virtual Machine. With most Java distributions, this can be done by using the -Xss option of the java command, like in the following example:

java -Xss1024k -jar epubcheck.jar moby-dick.epub
Clone this wiki locally