# How book-to-skill Handles MOBI, AZW, and AZW3 E-Book Files

> Discover how book-to-skill handles MOBI AZW and AZW3 files. Learn about its exclusive use of Calibre's ebook-convert CLI for binary format conversion, avoiding native Python parsing.

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

---

**book-to-skill processes MOBI, AZW, and AZW3 files exclusively through Calibre's `ebook-convert` CLI tool, treating them as binary formats that require external conversion rather than native Python parsing.**

The open-source project `virgiliojr94/book-to-skill` provides a specialized extraction pipeline for e-book formats lacking robust pure-Python parsers. For Amazon's proprietary formats—MOBI, AZW, and AZW3—the system delegates conversion entirely to Calibre's command-line utilities, implementing strict dependency validation before processing.

## Configuration of Calibre-Only Extensions

In [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py), the tool explicitly registers MOBI, AZW, and AZW3 as **Calibre-dependent formats** through the `CALIBRE_EBOOK_EXTENSIONS` tuple. This configuration at lines 37-40 serves as the canonical registry that routes these file types through the external conversion pipeline, distinguishing them from formats handled by native Python libraries.

```python

# From book_to_skill/config.py (simplified conceptual view)

CALIBRE_EBOOK_EXTENSIONS = ('.mobi', '.azw', '.azw3')

```

## Hard Dependency on Calibre CLI

Unlike EPUB or PDF handling, which may utilize Python packages such as `ebooklib` or `PyPDF2`, MOBI/AZW/AZW3 processing requires the external `ebook-convert` binary. The [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py) module declares this as a **mandatory system dependency** at lines 61-68, ensuring the extraction pipeline acknowledges that no fallback parser exists for these formats.

## Pre-Flight Validation and Error Handling

Before any content extraction occurs, the `prepare_dependencies()` function in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) performs extension-based validation. When encountering a file extension contained within `CALIBRE_EBOOK_EXTENSIONS`, the code verifies that `ebook-convert` exists on the system PATH (lines 30-34). 

If the binary is absent, the system immediately raises an `ExtractionError` with explicit installation instructions rather than attempting parsing and failing with cryptic errors. This early validation ensures users receive actionable feedback before the extraction process begins.

## The Calibre Extraction Pipeline

For validated files, the main extraction orchestration in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) routes execution through a dedicated Calibre branch. Upon detecting a matching extension (lines 50-58), the code invokes `extract_with_ebook_convert()` from [`book_to_skill/parsers/calibre.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/calibre.py).

This function (lines 10-24) performs the following operations:

1. Generates a temporary output path within the configured `OUTPUT_DIR`
2. Executes `ebook-convert [input] [output.txt]` as a subprocess
3. Reads the resulting plain-text file into memory
4. Returns the content for further processing

The extracted text subsequently flows through the standard **sanitization**, **token estimation**, and **metadata collection** pipelines, processing identically to PDF or EPUB content once converted.

## Running book-to-skill with Amazon Formats

Use the CLI entry point at [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) to process MOBI, AZW, or AZW3 files:

```bash

# Basic extraction of a MOBI file

python3 scripts/extract.py path/to/book.mobi

# Disable interactive installation prompts for CI environments

python3 scripts/extract.py path/to/book.azw3 --install-missing no

```

For programmatic access within Python applications:

```python
from book_to_skill import extract

metadata = extract("path/to/book.azw")
print(metadata["text"][:200])          # First 200 characters of extracted text

print(metadata["extraction_method"])   # Output: "ebook-convert"

```

Both approaches require Calibre installed locally with `ebook-convert` available on the system PATH.

## Summary

- **MOBI, AZW, and AZW3** are registered in `CALIBRE_EBOOK_EXTENSIONS` inside [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py)
- The system mandates **Calibre's `ebook-convert`** binary as declared in [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py)
- **Pre-flight checks** in `prepare_dependencies()` verify tool availability before processing
- Extraction occurs via `extract_with_ebook_convert()` in [`book_to_skill/parsers/calibre.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/calibre.py)
- Converted text enters the standard sanitization pipeline identical to other formats

## Frequently Asked Questions

### Does book-to-skill require Calibre for MOBI files?

Yes. According to the source code in [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py), MOBI, AZW, and AZW3 formats have a **hard requirement** for the `ebook-convert` command provided by Calibre. No pure-Python fallback parser exists for these formats within the codebase.

### What happens if ebook-convert is not installed?

The `prepare_dependencies()` function in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) detects the missing binary during pre-flight validation and raises an `ExtractionError` with clear installation instructions. The extraction aborts before any file processing begins, preventing partial or corrupted outputs.

### Can I convert AZW3 files without installing the full Calibre suite?

No. The `extract_with_ebook_convert()` function in [`book_to_skill/parsers/calibre.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/calibre.py) explicitly invokes the Calibre CLI tool. The repository contains no alternative parsing logic for these proprietary Amazon formats, making Calibre a non-negotiable system dependency for AZW3 support.

### How does the error handling differ between Calibre and native formats?

For native formats like EPUB, missing dependencies may trigger interactive installation prompts or alternative parser attempts. For MOBI/AZW/AZW3, the code path in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) (lines 30-34) treats missing `ebook-convert` as a fatal configuration error, immediately terminating with an explanatory exception rather than attempting recovery.