You validate an EPUB by running it through EPUBCheck, the official checker for EPUB files, which tests the file against the published EPUB rules and reports each fault with the file and line it sits on. You do not need the command line: free desktop apps and editor plugins run the same checker for you.
- Why Does an EPUB Need Validating Before You Upload It?
- What Is EPUBCheck, and What Does It Check?
- Which Tool Should You Use to Run EPUBCheck?
- How Do You Check an EPUB Inside Sigil or Calibre?
- Which Validation Errors Come Up Most Often, and How Do You Fix Them?
- What Does a Clean Validation Report Not Tell You?
- Frequently Asked Questions
Why Does an EPUB Need Validating Before You Upload It?
An EPUB is not a single document. It is a folder of separate files (one per chapter, plus the images, the stylesheet and a couple of files that list everything) zipped up together in a precisely defined arrangement, and retailers run their own checks on that arrangement when a file arrives. W3C, which owns the EPUB specification, puts the commercial position plainly in its guide to EPUBCheck: “Most retailers will not accept an EPUB file unless it successfully passes EPUBCheck scrutiny.” Checking the file yourself means you see the same faults they will, before the upload rather than after it.
The alternative is a slow loop. You upload, wait for processing, receive a rejection notice that may describe the problem only in general terms, guess at which part of the file it refers to, change something and upload again. Each turn of that loop can cost a day or more, and none of it tells you anything a validator would not have told you in seconds.
Validation also catches a second class of problem: faults that do not always trigger a rejection but do spoil the book on the device. A contents entry pointing at a chapter anchor that no longer exists, or a contents list running in a different order from the reading order, can leave a file that a shop accepts and a reader cannot navigate.
Both generations of the format are covered, and each is checked against its own rules. EPUB 2 and EPUB 3 keep the book’s contents list in different places: EPUB 3 calls that file the NAV document and EPUB 2 calls it the NCX file. You do not need to know which one you have before you run the checker.
What Is EPUBCheck, and What Does It Check?
EPUBCheck is the official conformance checker for EPUB publications, which is to say the tool that decides whether a file follows the rules. W3C unpacks its own phrase: it is “official” because the project belongs to W3C and sits with the same people who write the EPUB format, and it is a “conformance checker” because it tests whether a book meets what the format requires. It is free and open source, meaning anyone may use and inspect it, and it is maintained on W3C’s behalf by the DAISY Consortium. The current release is version 5.3.0. It checks an EPUB 3 file against the EPUB 3.3 rules and an EPUB 2 file against the EPUB 2 rules, working out which it is holding rather than asking you.
The W3C getting started guide lists what the tool scans: the structure of the container (the zipped arrangement of files), the package file and its metadata (the index that names every file in the book and the order they are read in), the markup inside the chapters, and whether the links between all of it hold together. Faults are reported as errors, which are breaches of the specification, or warnings, which are permitted but worth a look. Each carries a file path and a line number, so you are told where to go rather than left to search.
What EPUBCheck does not check
A clean EPUBCheck report has two blind spots, and neither of them announces itself. The first is editorial. W3C says so outright in the same guide: “EPUBCheck cannot play an editorial role.” It does not read the words, so it will not find a typo, a misspelling or an image dropped into the wrong chapter. A file can pass with every chapter title spelled wrong.
The second blind spot is accessibility, meaning how well the book works for readers using a screen reader or a large-print setting. EPUBCheck carries a few accessibility-related messages, covering things like table headings, but it is not an accessibility audit. The tool built for that job is Ace by DAISY, a separate free checker from the same organisation, which tests a book against the Web Content Accessibility Guidelines and the EPUB accessibility rules. The two are complementary rather than alternatives: passing EPUBCheck says nothing about whether your images carry alt text (the written description a screen reader speaks aloud) or whether the headings run in a sensible order. If accessibility matters for your book, run both, and treat Ace as an aid to a human review rather than a verdict.
Which Tool Should You Use to Run EPUBCheck?
EPUBCheck itself is distributed as a command line program, meaning you type an instruction into a terminal window rather than clicking anything. That is the official package, and it is why the tool has a reputation for being hard to approach. It does not have to be: W3C maintains a page of apps and tools that integrate EPUBCheck, and the applications listed there wrap the same checker in an ordinary window with a button.
Four routes lead to the same report. What separates them is how much setting up each needs, and whether your manuscript leaves your computer while it is checked.
| Route | Example | Where your file goes | Best for |
|---|---|---|---|
| Official command line tool | EPUBCheck 5.3.0 from W3C | Stays on your computer | Checking many files, or scripting the check into a routine |
| Desktop app with a window | pagina EPUB-Checker; EPUBCheckGUI | Stays on your computer | The full checker with nothing to type and nothing uploaded |
| Plugin inside an EPUB editor | EPUBCheck plugins for Sigil and Calibre | Stays on your computer | Checking and fixing in one place, without switching programs |
| Browser upload | Draft2Digital’s Epub Validator | Uploaded to someone else’s server | A quick one-off check on a machine you cannot install software on |
Three of those are worth naming. pagina EPUB-Checker runs on Windows, macOS and Linux, and so does EPUBCheckGUI; W3C lists both, and both run the official checker rather than an approximation of it. Draft2Digital’s Epub Validator works through a web page and without an account, so there is nothing to install; you upload the file and the checking happens on Draft2Digital’s servers rather than on your machine. For a book going on sale shortly that trade rarely matters. For a manuscript under embargo, or one covered by a confidentiality agreement, it does, and a desktop app avoids the question.
How Do You Check an EPUB Inside Sigil or Calibre?
Sigil and Calibre are two free programs for opening up an EPUB and editing what is inside it. Both can run EPUBCheck through an add-on, and both also carry a lighter built-in check of their own. The two kinds of check are worth keeping apart, because they answer different questions.
Calibre’s editor has a Check book tool, reached via Tools then Check book. The Calibre manual describes its purpose as searching “your book for problems that could prevent it working as intended on actual reader devices”, and the most useful part is what happens next: clicking an entry in the results explains the error and, where the fault can be repaired mechanically, offers to fix it. Double-clicking opens the file at the offending line. It is a device-behaviour check rather than a specification check, so it is a fast way to clear obvious breakage, not a substitute for the conformance report a retailer will run.
Sigil has a built-in check that confirms each chapter file is properly formed. Chapter files are written in the same kind of code as a web page, where each instruction has to be opened and closed in the right order, and this check confirms that much. It catches broken code but not rule breaches. For the full check, W3C’s list points to an EPUBCheck add-on for Sigil and a matching one for Calibre, both distributed through the MobileRead forums. Those run the real checker inside the editor, which is the arrangement worth having: you get the authoritative result and you are already in the program where you would fix it.
One older route is worth naming so you do not lose time on it. FlightCrew, the validation add-on that many Sigil tutorials still point to, checks EPUB 2 files only. Its code repository was archived by its owner in July 2023 and is now read only, so it has had no updates since. It still installs and it still works on what it covers; it simply does not cover EPUB 3, which is what most new files are. The EPUBCheck add-on above does.
Which Validation Errors Come Up Most Often, and How Do You Fix Them?
A first EPUBCheck report is usually shorter than it looks, because the same few faults come up again and again. Knowing the shape of each makes the report much faster to work through.
Missing or malformed metadata
Every EPUB must carry a title, a language and a unique identifier in its package file. Conversion tools sometimes drop one of the three, and the result is an error before the checker has looked at a single chapter. You can put them back in Sigil’s metadata editor, or by editing the package file directly if you are comfortable doing that.
Foreign image formats with no fallback
Image format rules are widely stated incorrectly, so it is worth being precise. EPUB names four image formats that every reading device has to handle: JPEG, PNG, GIF and SVG. A newer format such as WebP is allowed in the book, but only offered alongside one of those four, never on its own: the markup has to name a JPEG or PNG as the version a device should use if it cannot read the newer file. Supply the newer format by itself and EPUBCheck reports that a fallback must be provided. For almost every author the practical answer is the simple one: save the image as JPEG or PNG and the question does not arise.
Colour mode is a separate matter, and the EPUB rules do not mention it. Nothing in EPUBCheck’s published list of messages refers to CMYK, RGB or colour space at all, so a CMYK image (one prepared for a printing press) does not fail validation. It can still be a problem on the device: reading apps and browsers handle CMYK images inconsistently, and some will show nothing at all. So convert images taken from a print layout to RGB, the screen colour mode, because of how they may otherwise display, not because a validator will stop you.
Contents and reading-order mismatches
Three separate records have to agree about the chapters in a book. The package file names every file the book contains, and it also sets the order those files are read in. The contents list, kept in the NAV document in EPUB 3 or the NCX file in EPUB 2, is what the reader taps to jump around. A chapter that is named as part of the book but left out of the reading order, or a contents entry pointing at a place in the text that no longer exists, breaks that agreement. Both turn up after chapters have been split, merged or renamed, because renaming a file updates one record and not the others.
Broken internal links and duplicate IDs
Cross-references, footnotes and endnotes all work by linking one point in the book to another, and renaming a chapter file breaks every link pointing into it. Duplicate identifiers are the mirror image: each spot a link can jump to needs its own unique name within its file, and if two spots share a name the link no longer has one destination.
Stylesheet problems
The stylesheet is the file that sets how the book looks: typeface, spacing, indents. EPUBCheck reads it and reports several things, among them a stylesheet it cannot parse at all, a property the EPUB rules exclude, and a rule that pins something to a fixed position on the page, which has no meaning in a book whose text rearranges itself to fit the screen. Files exported from Word or InDesign often carry a great deal of styling that does nothing useful in an ebook. Cutting the stylesheet back to the properties that work reliably, typeface, margin, padding, alignment and line spacing among them, clears most of these reports and tends to improve how the book reads as well.
What Does a Clean Validation Report Not Tell You?
A clean EPUBCheck report means the file is built correctly. It does not mean the book is right, and the gap between those two is where the remaining work sits.
Links are the clearest example. A validator confirms that every internal link resolves to a file that exists; it cannot know whether it resolves to the correct file. A contents entry pointing at chapter eleven instead of chapter twelve is a valid link to a valid target, and it passes cleanly. At ebookpbook the testing pass on every ebook includes hand-checking hyperlinks for this reason: contents entries, chapter cross-references, footnote and endnote links, and external web addresses, each one followed to see where it actually lands. We have not found a tool that can do this part, because the question is about meaning rather than structure.
The same applies to the two blind spots above. Typos survive validation. So does an image with no alt text, unless you run Ace as well. And a book can follow every rule and still read badly on a six-inch screen, which is why opening the finished file on a real device, or at least in a reading app rather than a preview pane, is worth the ten minutes it takes.
Validating an EPUB costs minutes and removes a whole category of avoidable delay. Pick whichever of the four routes suits how you work, fix the errors, read the warnings and decide which ones matter for your book, then check the things the validator was never built to see.
Frequently Asked Questions
Do I need to validate my EPUB if I am only uploading to Amazon KDP?
It is worth doing. KDP runs its own checks on an incoming file, and what comes back may not name the specific fault. Validating first means you see the errors yourself, each with the file and line it sits on, which often turns several upload attempts into one.
Is EPUBCheck free to use?
Yes. EPUBCheck is open source, it is a W3C project maintained by the DAISY Consortium, and it can be downloaded at no cost from the W3C EPUBCheck site. The desktop applications and editor add-ons named in this article are free to use as well.
Do I need to use the command line to run EPUBCheck?
No. The official package is a command line program, but W3C maintains a list of apps and tools that put an ordinary window on the same checker. pagina EPUB-Checker and EPUBCheckGUI both run on Windows, macOS and Linux, and there are EPUBCheck add-ons for the Sigil and Calibre editors.
What is the difference between an error and a warning in EPUBCheck?
An error is a breach of the EPUB specification, and retailers may reject a file that has one. A warning marks something the specification permits but that could still cause trouble on some devices. Fix the errors, then read the warnings and judge each against your book.
Will EPUBCheck tell me if my ebook is accessible?
Not really. EPUBCheck includes a few accessibility-related messages, but it checks the file against the EPUB rules rather than auditing it for accessibility. Ace by DAISY is the free tool built for that job, and it tests a book against the Web Content Accessibility Guidelines and the EPUB accessibility rules. Run both, and treat Ace as an aid to a human review rather than a pass mark.
How often should I validate during the EPUB creation process?
Run a check after each structural change, such as adding chapters, adding images or rebuilding the contents list, rather than once at the end. Errors found one at a time are easy to place; two dozen arriving together in a finished file are much harder to untangle.
