Dependencies for Extracting EPUB Files with book-to-skill

book-to-skill requires ebooklib and beautifulsoup4 for full-featured EPUB extraction, but automatically falls back to a standard-library-only implementation if these packages are missing.

The book-to-skill repository provides a robust EPUB extraction pipeline designed to work across diverse Python environments. According to the virgiliojr94/book-to-skill source code, the library implements two distinct extraction paths—one optimized for accuracy and another for zero-dependency portability.

Primary EPUB Dependencies

The recommended extraction method relies on two external packages specified in book_to_skill/dependencies.py (lines 40-44):

• ebooklib – Parses the EPUB container, OPF metadata, and navigation structure
• beautifulsoup4 (imported as bs4) – Handles HTML/XHTML content extraction with proper encoding detection

These dependencies are grouped together in the EPUB feature set. When you attempt to process an .epub file, the prepare_dependencies routine checks for their availability and invokes offer_dependency_install with the following parameters:

# book_to_skill/dependencies.py

if ext == ".epub":
    offer_dependency_install(
        feature="EPUB extraction",
        module_names=["ebooklib", "bs4"],
        fallback="a stdlib ZIP/HTML parser",
        install_mode=install_mode,
    )

The mapping from module names to installable packages is defined in book_to_skill/config.py (lines 47-55), ensuring that pip install ebooklib and pip install beautifulsoup4 resolve correctly.

Pure Standard Library Fallback

When ebooklib or bs4 is unavailable, book-to-skill automatically switches to extract_with_zipfile in book_to_skill/parsers/epub.py (lines 63-73). This implementation requires no external dependencies and uses only:

• zipfile – Extracts the EPUB archive (which is a ZIP container)
• re – Pattern matching for content navigation
• posixpath – Cross-platform path handling for OPF manifests
• html.parser – Simple HTML tokenization via the built-in parser

The fallback extractor parses the OPF spine to locate reading-order documents, then feeds each HTML/XHTML file through the internal _HTMLTextExtractor class.

Installing EPUB Dependencies

Automatic Installation via CLI

The command-line interface handles missing dependencies transparently:

# Extract an EPUB; missing packages will be offered for installation.

python -m book_to_skill.extract /path/to/book.epub

When the EPUB group is incomplete, you'll see a prompt to install ebooklib and bs4 with an option to proceed with the stdlib fallback instead.

Manual Installation

For environments where you want guaranteed full-featured extraction:

pip install ebooklib beautifulsoup4

Verification

Check dependency status before processing:

import subprocess, sys

# Run the built-in dependency check; informs you which packages are missing.

subprocess.run([sys.executable, "-m", "book_to_skill.extract", "--check"])

Programmatic Extraction with Dependency Awareness

Explicitly choose your extraction strategy based on availability:

from book_to_skill.parsers.epub import extract_with_ebooklib, extract_with_zipfile

epub_path = "my_book.epub"

# Try the rich extractor first; falls back to None if dependencies are missing.

text = extract_with_ebooklib(epub_path)
if text is None:
    # Use the pure-stdlib fallback.

    text = extract_with_zipfile(epub_path)

print(text[:500])  # Preview the extracted text

Feature Comparison: Primary vs. Fallback Extractor

Capability	extract_with_ebooklib	extract_with_zipfile
Dependencies	ebooklib, bs4	None (stdlib only)
Metadata extraction	Full OPF metadata	Limited spine parsing
Encoding handling	Automatic via bs4	UTF-8 with fallback
CSS/TOC awareness	Yes	Partial
Performance	Slower (rich parsing)	Faster (streamlined)

Key Source Files for EPUB Dependencies

File	Purpose
book_to_skill/dependencies.py	Defines EPUB dependency group and installation logic
book_to_skill/config.py	Maps module names to PyPI package specifications
book_to_skill/parsers/epub.py	Houses both extract_with_ebooklib and extract_with_zipfile

Summary

• Full EPUB extraction requires ebooklib and beautifulsoup4 as defined in book_to_skill/dependencies.py
• Zero-dependency fallback uses zipfile and html.parser from the Python standard library
• Automatic switching occurs when extract_with_ebooklib returns None due to missing imports
• Dependency installation can be triggered interactively via CLI or managed manually with pip

Frequently Asked Questions

What happens if I don't install ebooklib and beautifulsoup4?

The library automatically falls back to extract_with_zipfile, which uses only Python standard library modules (zipfile, re, html.parser) to extract text. You'll still get usable output, but with reduced metadata extraction and encoding robustness compared to the primary implementation.

Can I force the stdlib fallback even when dependencies are installed?

Yes. Import extract_with_zipfile directly from book_to_skill.parsers.epub and call it explicitly. This bypasses the dependency check entirely and uses the ZIP-based extractor regardless of what packages are installed in your environment.

Does book-to-skill install dependencies automatically?

Not automatically. The offer_dependency_install function in dependencies.py prints a message describing what's missing and prompts you to confirm installation. You can accept the prompt, decline and use the fallback, or skip the check by pre-installing the packages yourself.

Which extraction method produces better quality output?

extract_with_ebooklib produces superior results because ebooklib properly handles EPUB container structure, bs4 manages encoding detection and malformed HTML, and together they preserve document semantics. The stdlib fallback extracts readable text but may misorder content or struggle with unusual character encodings.

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