Running epubcheck on your computer

by Keith Fahlgren

epubcheck is a valuable tool for anyone working with EPUB documents. Many beginners choose to start using it via the online validator at http://threepress.org/document/epub-validate, but it’s a mistake to use that too often. More explicitly:

If you’re making more than 3 EPUBs this year, you must setup epubcheck on your computer

Why setup epubcheck locally? If you have a local copy, you can:

  • run it even if the online validator is down (it was this morning)
  • run any version of epubcheck you want (useful when new versions are near release)
  • run it more quickly
  • run it on a lot of documents quickly (with a little command-line-foo)

Warning

This is a brief description of how you might be able to run epubcheck locally. This isn’t a tech support site, so please don’t post system questions in the comments.

Setup for both platforms

  1. Ensure java is installed and in your PATH (Google is your friend if not)
  2. Download the “binary” release you’d like to use (probably the featured one) from the epubcheck downloads page
  3. Unzip the downloaded .zip file to somewhere on your computer
  4. Find the file epubcheck-[something].jar in the newly unzipped folder (and keep this window open)
  5. Find the EPUB file you’d like to validate (and keep this window open)

Each time you’d like to run epubcheck, you’ll need to ask the java command to run the epubcheck program (packaged as a .jar file) against your EPUB file. Happily, you can get drag and drop to help you with most of the filenames.

Windows

  1. Open the “Run…” menu using [Windows-key]+r, Start Menu->Run…, or turning it on for Vista.
  2. In the “Run…” menu, type cmd.exe.
  3. In the new Command Prompt window (the “prompt”), type java -jar (note trailing space after “-jar”).
  4. Drag the epubcheck .jar file from the unzipped folder into the Command Prompt window (the location of the file ["path"] should be copied).
  5. Type another space in the terminal window after the .jar filename.
  6. Similarly, drag the EPUB file from wherever into the Command Prompt window (it’s path should also be copied).
  7. Press Enter.
  8. Note the results in the Command Prompt window (No errors or warnings detected means it passed).

Mac

  1. In the Finder, to Go->Utilities, then find the Terminal application (or do a Spotlight search for “Terminal”) and start it.
  2. In the new Terminal window (the “prompt”), type java -jar (note trailing space after “-jar”).
  3. Drag the epubcheck .jar file from the unzipped folder in the Finder into the Terminal window (the location of the file ["path"] should be copied).
  4. Type another space in the terminal window after the .jar filename.
  5. Similarly, drag the EPUB file from wherever in the Finder into the Terminal window (it’s path should also be copied).
  6. Press Return.
  7. Note the results in the Terminal window (No errors or warnings detected means it passed).

Linux

Ha, you’re on your own! (But do see the good comment from Toby Stevenson, below.)

Other tools

Now that you’ve mastered the above, you can try to run the epubpreflight checking tool in the same manner. It helps check if files are too big for the older Sony Reader devices, for example.