# How book-to-skill Handles MOBI, AZW, and AZW3 File Formats

> Discover how book-to-skill processes MOBI, AZW, and AZW3 files using Calibre's ebook-convert. Learn about its external dependency approach and lack of Python fallback for these ebook formats.

- Repository: [Virgilio Junior/book-to-skill](https://github.com/virgiliojr94/book-to-skill)
- Tags: deep-dive
- Published: 2026-08-24

---

**book-to-skill processes MOBI, AZW, and AZW3 files exclusively through Calibre's `ebook-convert` command-line tool, treating these formats as external dependencies with no pure-Python fallback.**

The `virgiliojr94/book-to-skill` repository implements a dedicated extraction pipeline for Amazon's proprietary e-book formats. When you provide a MOBI, AZW, or AZW3 file, the system validates the presence of Calibre's conversion utility before attempting extraction, routing these formats through a specialized parser that executes shell commands and processes the resulting plain-text output.

## Format Registration and Extension Mapping

In [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py), the three formats are explicitly categorized as requiring external conversion tools. Lines 37-40 define the `CALIBRE_EBOOK_EXTENSIONS` tuple, which includes `.mobi`, `.azw`, and `.azw3` alongside other Calibre-dependent formats.

This centralized registry allows the extraction logic to quickly identify which files require external binary processing rather than native Python parsing. The configuration serves as the single source of truth for determining when to invoke the Calibre-specific dependency checks.

## Dependency Validation and Pre-flight Checks

Before any conversion occurs, [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py) declares a hard requirement for the `ebook-convert` binary. Lines 61-68 specify this external dependency, marking it as mandatory for MOBI/AZW/AZW3 processing.

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 a pre-flight validation at lines 30-34. If the file extension appears in `CALIBRE_EBOOK_EXTENSIONS` but the `ebook-convert` command is absent from the system PATH, the function raises an `ExtractionError` with explicit installation instructions. This early failure prevents partial processing and provides clear feedback to users about missing Calibre installations.

## The Calibre Extraction Pipeline

When processing begins, the main extraction logic in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) routes MOBI, AZW, and AZW3 files through a dedicated branch. Lines 50-58 check if the extension exists in the Calibre registry, then delegate to `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).

The parser function at lines 10-24 executes the `ebook-convert` CLI with the source file and a temporary output path within the `OUTPUT_DIR` working directory. After the subprocess completes, it reads the generated plain-text file and returns the contents. If the conversion fails due to binary corruption or missing dependencies, the function propagates the error with detailed stderr output.

Once extracted, the plain-text undergoes identical sanitization, token estimation, and metadata collection as EPUB or PDF inputs, ensuring consistent downstream processing regardless of the original format.

## Practical Usage Examples

You can extract Amazon format files using the command-line interface or Python API.

### CLI Extraction

```bash

# Extract 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

```

### Programmatic Access

```python
from book_to_skill import extract

# Process an AZW file

metadata = extract("path/to/book.azw")

# Access extracted text and method information

print(metadata["text"][:200])          # First 200 characters

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

```

Both approaches require Calibre installed and `ebook-convert` available on your system PATH.

## Summary

- **book-to-skill** treats MOBI, AZW, and AZW3 as Calibre-exclusive formats with no native Python parser.
- The `CALIBRE_EBOOK_EXTENSIONS` tuple in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) registers these formats for external processing.
- `prepare_dependencies()` validates the presence of `ebook-convert` before extraction, raising `ExtractionError` if Calibre is missing.
- The extraction pipeline routes these files through `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), which shells out to the Calibre CLI.
- Converted plain-text passes through the standard sanitization and metadata collection pipeline used for other formats.

## Frequently Asked Questions

### Why doesn't book-to-skill use a native Python parser for MOBI files?

Amazon's MOBI, AZW, and AZW3 formats employ proprietary encoding schemes and optional DRM protection that lack robust pure-Python implementations. The project intentionally delegates to Calibre's `ebook-convert` tool to ensure accurate handling of complex formatting, dictionary indexes, and older MOBI variants that would require extensive reverse-engineering to parse natively.

### What happens if Calibre is not installed when processing an AZW3 file?

The system raises an `ExtractionError` during the dependency preparation phase in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py). This occurs before any file processing begins, providing an immediate error message directing you to install Calibre. The application will not attempt partial extraction or produce corrupted output.

### Can I process DRM-protected Kindle files with book-to-skill?

No. While `book-to-skill` can invoke `ebook-convert` on AZW and AZW3 files, Calibre's conversion tool respects DRM restrictions. If the input file contains active digital rights management, `ebook-convert` will fail and the parser will return the conversion error. You must remove DRM through legal means before extraction will succeed.

### Does the Calibre extraction path differ from EPUB processing in the final output?

No. After `extract_with_ebook_convert()` returns the plain-text content, the pipeline converges with EPUB and PDF processing. The extracted text undergoes identical token estimation, whitespace normalization, and metadata attachment, ensuring consistent API responses regardless of whether the source was a MOBI, EPUB, or AZW3 file.