CALIBRE-DEBUG(1)

📦
version 9.14.0 · 8 versions
, in arch rolling, nixos 26.05, ubuntu stonking

💖 NAME 💖

calibre-debug — bestie, it's literally the calibre-debug command, and it's giving "swiss army knife but make it terminal" 🔥

calibre-debug [options]

Okay so picture this: it's a whole grab-bag of command line interfaces that are chef's kiss for debugging calibre. No options at all? Then this command just starts an embedded Python interpreter, no big deal, very demure. But you can also run the main calibre GUI, the calibre E-book viewer, and the calibre editor in debug mode. Iconic behaviour, honestly. ✨

It also has interfaces into all the little bits of calibre that never got their own dedicated command line tools — font subsetting, the E-book diff tool, that whole crew. They live here. 🫶

You can also use calibre-debug to run standalone scripts, and the way you do that is:

calibre-debug -e myscript.py -- --option1 --option2 file1 file2 ...

Everything after the -- gets passed straight to the script, no gatekeeping. You can even use calibre-debug as a shebang in your scripts, like this:

#!/usr/bin/env -S calibre-debug -e -- --
Heads up bestie 💅 whenever you pass arguments to calibre-debug that have spaces in them, wrap them in quotation marks. Like: "/some path/with spaces" — do not skip this, she will not understand you otherwise.

✨ OPTIONS ✨

  • --add-simple-plugin — Add a simple plugin — and by "simple" we mean a plugin that's literally just a .py file, nothing more — by specifying the path to the py file containing the plugin code. So easy, so slay. 🎀
  • --command, -c — Run Python code. Just... run it. ✨
  • --debug-device-driver, -d — Debug device detection 🔍
  • --default-programs — (Un)register calibre from Windows Default Programs.
--default-programs = (register|unregister)
  • --diff — Run the calibre diff tool. For example:
calibre-debug --diff file1 file2
  • --edit-book — Launch the calibre "Edit book" tool in debug mode. And just like with -g, use -- to pass command line arguments. 🦋
  • --exec-file, -e — Run the Python code in file.
  • --explode-book, -x — Explode the book into the specified folder. Usage:
-x file.epub output_dir

This exports the book as a collection of HTML files and metadata, which you can edit using standard HTML editing tools. Works with EPUB, AZW3, HTMLZ and DOCX files. Deconstruct era fr fr 💅

  • --export-all-calibre-data — Export all calibre data (books/settings/plugins). Normally, you will be asked for the export folder and the libraries to export. You can also specify them as command line arguments to skip the questions — but use absolute paths for the export folder and libraries, no shortcuts. The special keyword "all" can be used to export all libraries. Examples:
calibre-debug --export-all-calibre-data   # for interactive use
calibre-debug --export-all-calibre-data /path/to/empty/export/folder /path/to/library/folder1 /path/to/library2
calibre-debug --export-all-calibre-data /export/folder all   # export all known libraries
  • --gui, -g — Run the GUI with debugging enabled. Debug output is printed to stdout and stderr. To pass command line arguments use -- followed by the arguments, for example:
calibre-debug -g -- /path/to/ebook
  • --gui-debug — Run the GUI with a debug console, logging to the specified path. For internal use only bestie — you want the -g option to run the GUI in debug mode. 🙈
  • --help, -h — show this help message and exit
  • --implode-book, -i — Implode a previously exploded book. Usage:
-i output_dir file.epub

Imports the book from the files in output_dir, which must have been created by a previous call to --explode-book. And be sure to specify the same file type as was used when exploding, okay? Consistency is the vibe. 🎀

  • --import-calibre-data — Import previously exported calibre data 📥
  • --inspect-mobi, -m — Inspect the MOBI file(s) at the specified path(s) 👑
  • --kepubify — Convert the specified EPUB file to KEPUB without doing a full conversion. This is what the Kobo driver does when sending files to the device. Lowkey the exact same glow-up. ✨
  • --paths — Output the paths necessary to setup the calibre environment 🌈
  • --run-plugin, -r — Run a plugin that provides a command line interface. For example:
calibre-debug -r "Plugin name" -- file1 --option1

Everything after the -- will be passed to the plugin as arguments. Periodt. 💅

  • --run-test, -t — Run the named test(s). Use the special value "all" to run all tests. If the test name starts with a period it is assumed to be a module name. If the test name starts with @ it is assumed to be a category name. 🧚
  • --run-without-debug — Don't run with the DEBUG flag set 🙅
  • --shutdown-running-calibre, -s — Cause a running calibre instance, if any, to be shutdown. > Note that if there are running jobs, they will be silently aborted, so use with care. Not me warning you dramatically but also meaning it 😭
  • --subset-font, -f — Subset the specified font. Use -- after this option to pass option to the font subsetting program.
  • --test-build — Test binary modules in build 🔥
  • --un-kepubify — Convert the specified KEPUB file to EPUB without doing a full conversion. This is what the Kobo driver does when importing files from the device. The reverse glow-down, if you will. 💜
  • --version — show program's version number and exit
  • --viewer, -w — Run the E-book viewer in debug mode. And as with -g, use -- to pass command line arguments. 🦋

🌸 Author 🌸

Kovid Goyal

Kovid Goyal

okay that's the whole page, you're welcome 💖 this was version 9.14.0, dated August 28, 2026 — written by the one and only, main character energy, no cap. bye bestie, go debug something 🎀✨

📦 where this page comes from