# How to Check for Missing Dependencies in book-to-skill: A Complete Guide

> Learn how to check for missing dependencies in book-to-skill using the --check flag or run_dependency_check() function. Ensure all required Python packages and system tools are installed for seamless document processing.

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

---

**Use the `--check` flag or call `run_dependency_check()` from `book_to_skill.dependencies` to scan for optional Python packages and system tools required for specific document formats.**

The **book-to-skill** repository provides a robust pre-flight dependency validation system that audits your environment before extracting text from books. This check identifies which optional extractors are available—such as `pypdf` for PDFs or `docling` for modern document formats—and reports exactly which system commands or Python modules need installation for optimal performance.

## Understanding the Dependency Check Architecture

The dependency validation workflow spans three core files that work together to detect, report, and guide installation of missing components.

### Core Detection Logic in [`dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/dependencies.py)

The [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py) module defines the **`DEPENDENCY_GROUPS`** matrix and implements **`run_dependency_check()`**, the central function that orchestrates the scan. This function iterates through format-specific dependency groups and uses **`python_module_available()`** to test for Python packages and **`shutil.which()`** to locate system binaries like `pdftotext` or `ebook-convert`.

When executed, the checker evaluates each format against optional criteria such as `any_of_modules` or `any_tool_suffices`, which allow fallback extractors to satisfy requirements. The function returns `0` regardless of missing optional dependencies, ensuring the check itself never blocks execution while still providing actionable guidance.

### CLI Integration via [`utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/utils.py)

The [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) file handles command-line argument parsing. Around line 1015, the code detects the **`--check`** flag and immediately routes execution to `run_dependency_check()` before exiting. This ensures users can verify their environment without triggering a full extraction job.

### Entry Point in [`extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/extract.py)

The [`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py) script serves as the user-facing entry point, forwarding `sys.argv` to `book_to_skill.utils.main()`. Because this script passes all arguments through, supplying `--check` to [`extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/extract.py) triggers the identical dependency report logic used by the module-level invocation.

## Running the Dependency Check

You can invoke the dependency validator through three methods depending on your workflow:

### Command Line Usage

Run the built-in check using the module execution syntax or the legacy script:

```bash

# Modern module invocation

python -m book_to_skill --check

# Legacy extractor script (identical functionality)

python scripts/extract.py --check

```

### Programmatic Verification

Import the check function directly into your Python code to validate dependencies during application startup:

```python
from book_to_skill.dependencies import run_dependency_check

# Returns 0 even if optional dependencies are missing

exit_code = run_dependency_check()

```

## Interpreting the Results

The dependency check outputs a formatted status table indicating availability for each document format. A typical report resembles:

```

book-to-skill — dependency check

  PDF (text-heavy)
      ✗ python: pypdf
        ↳ a `pypdf` command exists at /usr/local/bin/pypdf, so it is installed in an isolated environment …
      ✗ python: pdfminer
      ✗ system: pdftotext (poppler-utils)
      → fallback available (install for best quality) — any one of pdftotext / pypdf / pdfminer is enough

```

When gaps exist, the tool appends a final block containing exact installation commands tailored to your environment:

```

To enable the best extractor for every format, install the missing pieces:

  /usr/bin/python3 -m pip install pypdf pdfminer
  # poppler-utils: sudo apt install poppler-utils

```

Key file paths referenced throughout this process include:
- **[`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py)** – Houses the `DEPENDENCY_GROUPS` matrix and detection logic
- **[`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py)** – Parses `--check` flag and coordinates execution
- **[`scripts/extract.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/scripts/extract.py)** – Command-line wrapper that forwards arguments
- **[`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py)** – Defines `PYTHON_DEPENDENCIES` mappings used by the checker

## Summary

- **Use `python -m book_to_skill --check`** to run a comprehensive audit of optional extractors before processing documents
- The **`run_dependency_check()`** function in [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py) scans for both Python modules (like `pypdf`, `docling`, `bs4`) and system commands (like `pdftotext`, `ebook-convert`)
- The check supports **fallback semantics**—if `any_of_modules` is specified for a format, having one available dependency satisfies the requirement
- The tool returns **exit code 0** regardless of missing optional dependencies, providing installation suggestions without blocking workflows
- Configure additional dependencies in [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) via the `PYTHON_DEPENDENCIES` mapping

## Frequently Asked Questions

### How do I check if book-to-skill has all required dependencies installed?

Run `python -m book_to_skill --check` from your terminal. This executes the `run_dependency_check()` function from [`book_to_skill/dependencies.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py), which scans for Python packages using `python_module_available()` and system binaries using `shutil.which()`, then prints a table showing which optional extractors are available for PDF, EPUB, HTML, and other formats.

### What does the dependency check output tell me?

The output lists each supported document format with checkmarks or X-marks indicating whether specific Python modules (like `pypdf` or `pdfminer`) and system tools (like `pdftotext` from poppler-utils) are present. Formats marked with "fallback available" indicate that while the optimal extractor is missing, an alternative method exists. The final section provides exact `pip install` and `apt install` commands to resolve gaps.

### Can I run the dependency check programmatically without using the CLI?

Yes. Import `run_dependency_check` from `book_to_skill.dependencies` and call it directly in your Python code. The function always returns `0` (success) even when optional dependencies are missing, making it safe to include in automated setup scripts or application initialization routines without disrupting execution flow.

### Why does book-to-skill use optional dependencies instead of requiring all packages upfront?

The repository implements a **plugin-style architecture** where extractors for specific formats (MOBI/AZW requiring `ebook-convert` from Calibre, or modern PDF parsing via `docling`) are optional. This design keeps the base installation lightweight while the `--check` flag allows users to verify exactly which extractors are active for their specific document conversion needs.