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

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

The 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

The 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

The 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 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:

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

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 – Houses the DEPENDENCY_GROUPS matrix and detection logic
• book_to_skill/utils.py – Parses --check flag and coordinates execution
• scripts/extract.py – Command-line wrapper that forwards arguments
• 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 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 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, 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.

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