Requirements for MOBI/AZW/AZW3 Extraction in Book-to-Skill: Calibre Setup Guide

Book-to-Skill requires Calibre's ebook-convert command-line tool to be installed system-wide and accessible on the PATH to extract text from MOBI, AZW, and AZW3 files.

Book-to-Skill is an open-source utility that converts ebooks into AI-ready skill formats. While the tool handles most document types with internal parsers, MOBI-family Kindle formats demand specific external dependencies to decode proprietary Amazon encodings.

Why Calibre is Required for Kindle Formats

Unlike EPUB or PDF files, MOBI, AZW, and AZW3 use proprietary binary formats that cannot be parsed reliably with pure Python libraries. According to book_to_skill/dependencies.py at line 317, Calibre is explicitly declared as the only hard requirement, and specifically for MOBI/AZW files. The project delegates conversion to Calibre's battle-tested engine rather than reimplementing complex format parsers.

Prerequisites: Installing Calibre and Verifying ebook-convert

Before processing any MOBI-family files, you must install the Calibre application. This is a desktop application, not a Python package installable via pip, and it includes the ebook-convert CLI utility required by Book-to-Skill.

Verifying the Binary is on PATH

Book-to-Skill validates Calibre availability before attempting extraction. In book_to_skill/utils.py, the prepare_dependencies function (around line 10) executes shutil.which("ebook-convert") to verify the binary exists in your system PATH. If the check fails, the utility raises an ExtractionError immediately.

Verify your setup manually:

which ebook-convert

# Or on Windows:

where ebook-convert

How Book-to-Skill Handles MOBI/AZW/AZW3 Files

Format Detection via CALIBRE_EBOOK_EXTENSIONS

At line 808 of book_to_skill/utils.py, the constant CALIBRE_EBOOK_EXTENSIONS defines the tuple (".mobi", ".azw", ".azw3"). When the extraction pipeline receives a file matching these extensions, it routes processing to the Calibre parser rather than using the standard-library fallback.

The Conversion Subprocess

The actual conversion logic resides in book_to_skill/parsers/calibre.py. This module invokes:

subprocess.run(["ebook-convert", input_path, output_path, "--to", "txt"])

The module manages temporary file creation, executes the conversion, reads the resulting plain text, and handles cleanup. This subprocess call is the core mechanism for MOBI/AZW/AZW3 extraction in Book-to-Skill.

Error Handling When Calibre is Missing

If you attempt MOBI/AZW/AZW3 extraction without Calibre installed, Book-to-Skill aborts with an explicit error message:

MOBI/AZW/AZW3 extraction requires Calibre's ebook-convert command.
Install Calibre and ensure ebook-convert is on PATH, then rerun this command.

This error originates from the validation logic in utils.py when shutil.which("ebook-convert") returns None, preventing confusing mid-process failures.

Programmatic Usage Example

For developers integrating Book-to-Skill into Python applications:

from book_to_skill.utils import extract_text
from book_to_skill.exceptions import ExtractionError

try:
    text = extract_text("/path/to/book.azw3")
    print(f"Successfully extracted {len(text)} characters")
except ExtractionError as e:
    print(f"Extraction failed: {e}")

Batch Processing Verification

To verify all dependencies including Calibre before a batch operation:

book-to-skill --check

Expected output confirms:

Calibre is the only hard requirement, and only for MOBI/AZW files.

Summary

• Calibre is mandatory for MOBI, AZW, and AZW3 processing; no Python pip package substitutes for the external application.
• ebook-convert must be on PATH; Book-to-Skill validates this via shutil.which() in utils.py before extraction.
• Format detection relies on the CALIBRE_EBOOK_EXTENSIONS tuple in utils.py (line 808) to trigger Calibre routing.
• Conversion execution occurs in parsers/calibre.py using subprocess.run() to invoke the external tool.
• Clear error messages guide users to install Calibre when the binary is missing, as defined in the dependency validation workflow.

Frequently Asked Questions

Do I need Calibre to process EPUB or PDF files with Book-to-Skill?

No. According to the dependency declarations in dependencies.py (line 317), Calibre is the only hard requirement and applies exclusively to MOBI, AZW, and AZW3 formats. EPUB and PDF files use internal parsers that rely only on standard Python libraries and require no external system tools.

How do I install Calibre for Book-to-Skill on a headless server?

Install the Calibre command-line tools using your package manager (e.g., apt install calibre on Ubuntu, brew install calibre on macOS, or calibre from conda-forge). Ensure the ebook-convert binary is accessible in the environment where you run Book-to-Skill, as verified by the prepare_dependencies function in utils.py.

What specific error appears if ebook-convert is not found?

Book-to-Skill raises an ExtractionError with the message: "MOBI/AZW/AZW3 extraction requires Calibre's ebook-convert command. Install Calibre and ensure ebook-convert is on PATH, then rerun this command." This occurs during the initialization phase in utils.py before any file conversion begins.

Can I use a custom Calibre binary path instead of the system PATH?

The current implementation in book_to_skill/parsers/calibre.py invokes ebook-convert directly via subprocess without configuration for custom binary paths. For non-standard installations, create a symlink or wrapper script that places the binary on the system PATH under the exact name ebook-convert, or modify the PATH environment variable before running Book-to-Skill.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}