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

> Set up Book-to-Skill for MOBI AZW AZW3 extraction. Learn the essential Calibre ebook-convert command-line tool requirements and PATH setup for seamless text extraction.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: how-to-guide
- Published: 2026-08-31

---

**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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```bash
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/calibre.py). This module invokes:

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```python
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:

```bash
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/utils.py) before extraction.
- **Format detection** relies on the `CALIBRE_EBOOK_EXTENSIONS` tuple in [`utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/utils.py) (line 808) to trigger Calibre routing.
- **Conversion execution** occurs in [`parsers/calibre.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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.