What Is an EPUB File? The Ebook Format Inside a ZIP, and How to Open and Fix One

7 How Do You Open EPUB Files? Phone, Mac, Windows and Python

FileInfo's program list names Apple Books, calibre, Adobe Digital Editions and Google Play Books. We tested on Linux, so the table marks what we tested and what we did not. Reading an EPUB file and checking one are different jobs, and the next sections cover both.

Open EPUB files on an iPhone, iPad or Mac

Apple Books is the built in reader. On a Mac, Apple's Books guide says to choose File > Import or drag the file into your library. It says many EPUB books import this way. We did not test Apple Books with any of our EPUB files.

If EPUB files will not import, do not edit them in place. Copy them first, and use our six step check to see which step fails. Apple's page names ACSM, AZW and ODM files as formats that open only in other apps, so those are not ordinary EPUB files.

Open EPUB files on Windows

A PC needs an app. calibre and Adobe Digital Editions are free, per FileInfo. Two vendors also list Windows viewers on their pages. The cards show what those pages say, and we tested neither program.

SysTools says its viewer previews EPUB files, searches them and shows images and links. It says the free version is view only and that saving needs the Pro version. It also says the viewer can recover corrupted EPUB files, which we could not test.

Freeviewer says its viewer opens EPUB files of any size on Windows and previews them in the free version. Its page lists Save As in one place and says the free version only previews in another, so test it on a copy before you rely on it.

Open EPUB files with Python

Install EbookLib with pip install EbookLib. It reads the metadata, the manifest and every page. The script prints the title and the number of pages in a test book we made. It counts the navigation file as a fourth page.

import ebooklib
from ebooklib import epub

book = epub.read_epub('g02_epub3.epub')
print(book.get_metadata('DC', 'title')[0][0])
print(len(list(book.get_items_of_type(ebooklib.ITEM_DOCUMENT))))

Our Test Book
4

EbookLib refused 11 of our 30 damaged EPUB files, and the error message did not say which step broke. If it raises an error, use our six step script to find the step and then repair the ZIP.

8 How Do You Check an EPUB File? Six steps, and the first failure names the problem

The script uses only Python's own modules. On a good EPUB file it prints one line. The listing shows the command and the result for the 9,089 byte book from the structure section.

python3 check_epub.py g02_epub3.epub
OK all 6 steps passed

The figure follows the order of the checks. Steps 1 and 2 are about the ZIP. Steps 3 and 4 follow the container and the package. Step 5 compares the lists, and step 6 opens the pages. The damage test lists ten causes behind the numbers.

Check EPUB files with Python

The script fails EPUB files that do not start with a ZIP header. It also fails every mimetype file that is not first and stored, every package with no identifier and every spine that points nowhere. It only warns about a missing modified date and an unlisted chapter.

import sys, zipfile, posixpath, unicodedata
import xml.etree.ElementTree as ET
from urllib.parse import unquote

C = '{urn:oasis:names:tc:opendocument:xmlns:container}'
O = '{http://www.idpf.org/2007/opf}'
DC = '{http://purl.org/dc/elements/1.1/}'

class Stop(Exception): pass

def check(path):
    warns = []
    def fail(step, msg): raise Stop('FAIL step %d: %s' % (step, msg))
    try:
        raw = open(path, 'rb').read()
        if raw[:4] != b'PK\x03\x04': fail(1, 'the file does not start with a ZIP header')
        try: z = zipfile.ZipFile(path)
        except Exception as e: fail(1, 'the ZIP cannot be read (%s)' % str(e)[:40])
        bad = z.testzip()
        if bad: fail(1, 'the ZIP entry %s fails its checksum' % bad)
        names = z.namelist()
        orig = {unicodedata.normalize('NFC', n): n for n in names}
        names = list(orig)
        def rd(n):
            try: return z.read(orig[n])
            except Exception as e: fail(1, '%s cannot be read (%s)' % (n, str(e)[:40]))
        if 'mimetype' not in names: fail(2, 'there is no mimetype file')
        info = z.getinfo('mimetype')
        if names[0] != 'mimetype': fail(2, 'mimetype is not the first file')
        if info.compress_type != 0: fail(2, 'mimetype is compressed')
        if info.extra: fail(2, 'mimetype has a ZIP extra field')
        if rd('mimetype') != b'application/epub+zip': fail(2, 'mimetype does not say application/epub+zip')
        if 'META-INF/container.xml' not in names: fail(3, 'there is no META-INF/container.xml')
        try: opf_path = ET.fromstring(rd('META-INF/container.xml')).find('.//%srootfile' % C).get('full-path')
        except Exception as e: fail(3, 'container.xml cannot be parsed (%s)' % str(e)[:40])
        if opf_path not in names: fail(3, 'container.xml names %s, which is not in the ZIP' % opf_path)
        try: pkg = ET.fromstring(rd(opf_path))
        except Exception as e: fail(4, '%s is not well formed (%s)' % (opf_path, str(e)[:40]))
        md = pkg.find(O + 'metadata')
        for tag in ('identifier', 'title', 'language'):
            if md is None or md.find(DC + tag) is None: fail(4, 'the package has no dc:' + tag)
        if (pkg.get('version') or '').startswith('3') and not any(m.get('property') == 'dcterms:modified' for m in md.iter(O + 'meta')):
            warns.append('WARN the EPUB 3 package has no dcterms:modified')
        base, man = posixpath.dirname(opf_path), {}
        for it in pkg.iter(O + 'item'):
            man[it.get('id')] = it
            p = unicodedata.normalize('NFC', posixpath.normpath(posixpath.join(base, unquote(it.get('href')))))
            if p not in names: fail(5, 'the manifest lists %s, which is not in the ZIP' % p)
        spine = [r.get('idref') for r in pkg.iter(O + 'itemref')]
        if not spine: fail(5, 'the spine is empty')
        for r in spine:
            if r not in man: fail(5, 'the spine points to %s, which is not in the manifest' % r)
        for r in spine:
            it = man[r]
            p = unicodedata.normalize('NFC', posixpath.normpath(posixpath.join(base, unquote(it.get('href')))))
            if it.get('media-type') != 'application/xhtml+xml':
                if it.get('media-type') == 'text/html': warns.append('WARN %s has the media type text/html' % p)
                continue
            try:
                data = rd(p); ET.fromstring(data); data.decode('utf-8')
            except Stop: raise
            except Exception as e: fail(6, '%s is not well formed UTF-8 XML (%s)' % (p, str(e)[:40]))
        listed = {unicodedata.normalize('NFC', posixpath.normpath(posixpath.join(base, unquote(i.get('href'))))) for i in man.values()}
        for n in names:
            if n.endswith('.xhtml') and n not in listed: warns.append('WARN %s is in the ZIP but not in the manifest' % n)
    except Stop as s:
        return [str(s)]
    return warns

if __name__ == '__main__':
    r = check(sys.argv[1])
    if not r: print('OK all 6 steps passed')
    for l in r: print(l)
    sys.exit(1 if any(l.startswith('FAIL') for l in r) else 0)

Here is what it printed for four damaged EPUB files. The first has the mimetype file second. The second has a spine that points to an unknown id. The third has one page with a broken tag. The fourth lacks chapter 3 in the manifest.

python3 check_epub.py c01.epub
FAIL step 2: mimetype is not the first file

python3 check_epub.py c22.epub
FAIL step 5: the spine points to nochapter, which is not in the manifest

python3 check_epub.py c26.epub
FAIL step 6: OEBPS/ch2.xhtml is not well formed UTF-8 XML (mismatched tag: line 11, column 2)

python3 check_epub.py c24.epub
WARN OEBPS/ch3.xhtml is in the ZIP but not in the manifest

The first line of every answer names the step and the cause. That is the fact a repair needs. The last answer is only a warning, because the file is valid, and readers still lose chapter 3 as the study shows.

What the script found in 30 damaged EPUB files

The script checks structure and does not scan for malware. It cannot judge the writing, the images or the layout. It reads only the first package file, so it warns about the second rendition in one public book. EPUBCheck is stricter on style rules.

Check an EPUB file by hand

You can do the first two steps in a terminal. The first command lists the files with their storage method, and the first row must be mimetype with the method Stored. The second prints the text of that file. The third tests the ZIP.

unzip -lv g02_epub3.epub | head -4
unzip -p g02_epub3.epub mimetype
unzip -tq g02_epub3.epub

Archive:  g02_epub3.epub
 Length   Method    Size  Cmpr    Date    Time   CRC-32   Name
--------  ------  ------- ---- ---------- ----- --------  ----
      20  Stored       20   0% 2026-10-22 10:00 2cab616f  mimetype
application/epub+zip
No errors detected in compressed data of g02_epub3.epub.

The first row must be mimetype with the method Stored. We tested these commands on Linux with unzip 6.00. We did not try them on a Mac. unzip passed all 7 mimetype copies, so it checks the ZIP and not the EPUB rules.

9 Are EPUB Files Safe to Open? Reading is safe, and the book inside can still contain scripts

The ending says nothing about safety. An EPUB file is a ZIP of pages, and its safety depends on who wrote it and what it contains. The table lists what to check, and every row ends with its source.

Why a reader is safer than an app

A reader prints what it finds. An ebook app builds the pages on screen, with fonts, images and scripts. We checked 83 EPUB files before and after every tool and script. The SHA256 hash of every file was the same.

Use a reader first when you are not sure what a file is. List the files with unzip. Read the package file as text. Look at the title and the identifier. Then decide, and keep the original untouched.

Why you should read the first bytes

A file that ends in .epub can be anything. A good EPUB file starts with the letters PK and has the word mimetype at byte 30. The Linux file command checks that, and our script checks it too. It named 23 of our 30 damaged EPUB files correctly.

11 How Do You Convert an EPUB File? PDF, DOCX, MOBI and plain text

Two kinds of work belong here. One writes the book in another format. The other unpacks the book into files. Choose by what you need next. The table lists what we found for the test book, and every row names its source.

Convert EPUB files with calibre

calibre reads the book and writes the format that the file ending asks for. We converted 5 books to 6 formats with it, which makes 30 conversions, and all 30 finished. The listing shows the commands we used.

ebook-convert book.epub book.pdf
ebook-convert book.epub book.docx
ebook-convert book.epub book.mobi
ebook-convert book.epub book.azw3
ebook-convert book.epub book.txt
pandoc book.epub -o book.docx
pandoc book.epub -o book.md --extract-media=media
unzip book.epub -d book_folder

The commands are the ones we used, with our file names changed to book. We tested them on Linux with calibre 7.6.0 and pandoc 3.1.3. In our reader test, pandoc needed 194 seconds for the longest public book, so wait before you stop a job.

Convert EPUB files with pandoc

pandoc reads an EPUB file and writes DOCX, ODT, HTML or Markdown. We converted the same 5 books to 4 formats, which makes 20 conversions, and all finished. For HTML and Markdown, ask for a media folder, or the images stay inside the book.

Text books come out well. Books made of images come out nearly empty, because they contain pictures and no text. Three of our public EPUB files are built that way, and pandoc wrote 3 to 39 characters for them. That is right, and not a failure.

Unpack EPUB files

Unpacking gives you the pages, styles and images as files. The command in the listing writes them into a folder. Editing them and zipping the folder again can break the book, as the mimetype section explains.