Documentation - Kepubify

Getting Started

Windows

Download kepubify-windows-32bit.exe or kepubify-windows-64bit.exe from the releases page. If you're unsure which one to choose, use kepubify-windows-32bit.exe.
Drag your books or folder of books onto the downloaded executable. The converted files will be in the current directory with the suffix _converted.

macOS

Download kepubify-darwin-64bit from the releases page. If you have a M1 chip, download kepubify-darwin-arm64 instead. You can also install kepubify with Homebrew.
Type chmod +x into the terminal (note the space at the end), drag the file you downloaded onto it (or type the path manually), and press enter.
Drag the file you downloaded onto the terminal again, then drag the folders or files onto it (or type them manually), pressing space before each one, then press enter. The converted files will be in your home folder with the suffix _converted.

Linux

Download the kepubify binary for your architecture from the releases page.
chmod +x the binary.
Run the binary with one or more files/directories to convert as arguments. The converted files will be in the current directory with the suffix _converted.

FreeBSD

Install kepubify with pkg install kepubify.
Run kepubify with one or more files/directories to convert as arguments. The converted files will be in the current directory with the suffix _converted.

Building from source / other

Install Go 1.16 or later if you haven't already done so.
Run go install github.com/pgaskin/kepubify/v4/cmd/kepubify@latest. The resulting binary will be in $HOME/go/bin, or whatever GOBIN is set to. If you are using Go 1.16, I also recommend adding -tags zip117 after go build for better performance.

Kepubify

About

Kepubify converts EPUBs to Kobo EPUBs.

Usage

Usage: kepubify [options] input_path [input_path]...

General Options:
  -v, --verbose   Show extra information in output
      --version   Show the version
  -h, --help      Show this help text

Output Options:
  -u, --update             Don't reconvert files which have already been converted (i.e. don't overwrite output files)
  -i, --inplace            Don't add the _converted suffix to converted files and directories
      --no-preserve-dirs   Flatten the directory structure of the input (an error will be shown if there are conflicts)
  -o, --output string      [>1 inputs || 1 file input with existing dir output]: Directory to place converted files/dirs under; [1 file input with
                           nonexistent output]: Output filename; [1 dir input]: Output directory for contents of input (default: current directory)
      --calibre            Use .kepub instead of .kepub.epub as the output extension (for Calibre compatibility, only use if you know what you are doing)
  -x, --copy strings       Copy files with the specified extension (with a leading period) to the output unchanged (no effect if the filename ends up the same)

Conversion Options:
      --smarten-punctuation        Smarten punctuation (smart quotes, dashes, etc) (excluding pre and code tags)
  -c, --css stringArray            Custom CSS to add to ebook
      --hyphenate                  Force enable hyphenation
      --no-hyphenate               Force disable hyphenation
      --fullscreen-reading-fixes   Enable fullscreen reading bugfixes based on https://www.mobileread.com/forums/showpost.php?p=3113460&postcount=16
  -r, --replace stringArray        Find and replace on all html files (repeat any number of times) (format: find|replace)
      --charset string             Override the HTML charset (use "auto" to detect it from the content) (default "utf-8")

Examples

For the following examples, replace kepubify with the path to the downloaded kepubify.

To convert a single book by dragging and dropping on Windows:
Just drag the original epub file over kepubify.exe. The resulting file will be saved to the same directory as the original epub.
To convert a folder of books by dragging and dropping on Windows:
Just drag the folder over kepubify.exe. The resulting file will be saved to the same directory as the originals, but with the suffix _converted.
To convert a single book:
kepubify /path/to/the/book.epub
The resulting file will be saved to the current directory.
To convert a single book with a different output folder:
kepubify --output "/path/to/save/the/book/" /path/to/the/book.epub
The resulting file will be saved to specified folder (in this example /path/to/save/the/book/).
To convert all books in the current folder into a folder called converted:
kepubify -o "converted" *.epub
To batch convert a directory of ebooks:
kepubify /path/to/the/books/
The converted books will be saved to the original dir with the suffix _converted (e.g. /path/to/the/books_converted).The directory structure of the source is preserved in the output.
To batch convert a directory of ebooks with a different output folder:
kepubify -o "/path/to/output/the/converted/books" /path/to/the/books/
The directory structure of the source is preserved in the output.
To convert a directory of ebooks, but skipping ones which have already been converted:
kepubify --update /path/to/the/books/
To convert a calibre library in-place:
kepubify --update --inplace --calibre /path/to/calibre/library/
To convert a folder of books directly on to a Kobo eReader, while simply copying PDF files:
kepubify --output /path/to/kobo/kepubify --update --copy .pdf /path/to/books/

Kepubify vs Calibre

There are a few reasons why you would want to use kepubify instead of the Calibre KEPUB plugin:

Kepubify is generally 40-60x faster than Calibre, and uses 15-30% less memory.
Kepubify modifies the source content less the Calibre, and it parses the HTML properly rather than using pattern matching. This often means that books which break when converted with Calibre will work fine with Kepubify.
Kepubify can run standalone or be embedded into other applications. For example, calibre-web uses kepubify internally for conversions.
Kepubify's output is usually closer to official KEPUB files than the Calibre plugin.

But, if Calibre works well for you right now, you already use it heavily for e-book management, and you're happy with it's performance and results, you can continue to use it.

Remember that it is possible to use kepubify to pre-convert individual books or your entire library, then import those into Calibre.

Converting your Calibre library with kepubify (Windows)

Open PowerShell.
Type $library = "C:\path\to\Calibre Library\", setting your library path accordingly, and press enter. This will set the path used in the next two commands.
Type C:\path\to\kepubify.exe --calibre --update --inplace "$library", setting the path to kepubify accordingly, and press enter. This will convert any unconverted books. If you also want to re-convert books which are already converted, remove the --update.
Type dir -Path "$library" -Filter *.kepub -Recurse | %{calibredb add -m 'ignore' $_.FullName} and press enter. This will add the converted books to the Calibre database.

Converting your Calibre library with kepubify (Linux/macOS)

Open a terminal window.
Type LIBRARY="/path/to/Calibre Library", setting your library path accordingly, and press enter. This will set the path used in the next two commands.
Type kepubify --calibre --update --inplace "$library", setting the path to kepubify accordingly, and press enter. This will convert any unconverted books. If you also want to re-convert books which are already converted, remove the --update.
Type find "$LIBRARY" -name '*.kepub' | xargs -I _ calibredb add -m 'ignore' _, and press enter. This will add the converted books to the Calibre database.

Seriesmeta

About

Note: I recommend using my new mod, NickelSeries, after you run seriesmeta once. NickelSeries will add built-in support for series metadata to Kobo's import process and eliminate the requirement to run seriesmeta every time you add books.

Usage

Usage: seriesmeta [options] [kobo_path]

Options:
  -h, --help         Show this help message
  -p, --no-persist   Don't ensure metadata is always set (this will cause series metadata to be lost if opening a book after an import but before a reboot)
  -n, --no-replace   Don't replace existing series metadata (you probably don't want this option)
  -u, --uninstall    Uninstall seriesmeta table and hooks (imported series metadata will be left untouched)

Arguments:
  kobo_path is the path to the Kobo eReader. If not specified, seriesmeta will try to automatically detect the Kobo.

NickelSeries

I've written a mod for the Kobo firmware, NickelSeries, which will add built-in support for series metadata to Kobo's import process and eliminate the requirement to run seriesmeta every time you add books.

After using seriesmeta to add metadata for existing books, I recommend installing NickelSeries. Note that you can safely use both at the same time, and neither conflict with Calibre.

Covergen

About

Cover thumbnails on Kobo devices can generated or re-generated using covergen. This will speed up library browsing, and will improve the quality of resized covers.

This tool is standalone, and will not conflict with Calibre.

Usage

Usage: covergen [options] [kobo_path]

Options:
  -a, --aspect-ratio float   Stretch the covers to fit a specific aspect ratio (for example 1.3, 1.5, 1.6)
  -g, --grayscale            Convert images to grayscale
  -h, --help                 Show this help message
  -i, --invert               Invert images
  -m, --method string        Resize algorithm to use (bilinear, bicubic, lanczos2, lanczos3) (default "lanczos3")
  -r, --regenerate           Re-generate all covers

Arguments:
  kobo_path is the path to the Kobo eReader. If not specified, covergen will try to automatically detect the Kobo.

Troubleshooting

Permission denied errors on macOS or Linux

Run chmod +x /path/to/kepubify from the terminal, replacing the path to kepubify as necessary.

Kobo Elipsa markup not available on sideloaded KEPUBs

See #66.

Bugs

To report bugs or request new features, open an issue, or send me an email at patrick (at) pgaskin (dot) net.