epubcheck 102: Running epubcheck
In part one of this series, we looked at why epubcheck is an important tool in any ebook maker’s toolchest. Today we look at how to use it.
OK, now that we know why to use epubcheck, let’s look at how. There are a couple ways to use epubcheck in your workflow, ranging from super easy to “yes. use the terminal” (which for some of us is also super easy 🙂 )
A very simple way to do one-off checks is to use the online validator created by the IDPF. Just upload your EPUB file and press the “validate” button. There are a few downsides to this version. First, it only accepts files up to 10MB. For most ebooks that’s probably fine, but for books with videos or lots of images you’ll need to look at a different solution. Secondly, this can be a tedious process if you need to check the file, then edit it, then re-check it. A rinse and repeat process might not be ideal with this tool.
As I’ve previously mentioned, Flight Deck is one of my favorite ebook validation tools. It has epubcheck built into its validation process. There’s a few advantages to using flight deck over the simple IDPF tool. First, it supports a larger maximum upload file size. It also offers additional validation services that are either required or recommended by ebook retailers.
There’s another benefit that isn’t as black and white worth discussing. As we’ll talk about in the next installment of this series, epubcheck’s error reporting can be a bit vague at times. The language its uses can be difficult to parse, and trying to solve some of the more abstract error messages can be a pain. Flight Deck tries to help by re-writing some of the error messages to be a little more human-friendly.
Like the IDPF tool, it may also not be great if you go through a lot of rinse and repeat to solve errors.
More than a few ebook creators I know swear by Pagina. It’s a desktop tool, and it has the added benefit of zipping up your unzipped EPUB file. This makes it much more useful in most people’s rinse and repeat workflows. It also offers translations of errors to other languages if you’d prefer something other than English.
(thanks to India Amos for reminding me of this great tool.)
I know, I know. The Terminal is scaaaaaary. So if it’s not your cup of tea, skip this part. If you do like to use the terminal or are considering building epubcheck into a more complicated workflow, read along.
Download the latest release from Github
All of epubcheck’s releases are available on Github here. Unless you know you want a beta release, I recommend downloading the “Latest Release” (as of this post that is 3.0.1).
Run the application
Once downloaded, running the script is as simple as running the following command in terminal
java -jar path/to/epubcheck-x.x.x.jar path/to/file.epub
epubcheck-x.x.x.jar is the name of the file you downloaded. (as of this post’s writing it would be
In the next part of the series we’ll look at some of the error messages you get from epubcheck and ways to fix your file.