# Dependencies for Extracting EPUB Files with book-to-skill

> Discover the dependencies for extracting EPUB files with book-to-skill. Learn about ebooklib and beautifulsoup4, and the fallback mechanism for seamless operation.

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

---

**`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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```python

# 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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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:

```bash

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

```bash
pip install ebooklib beautifulsoup4

```

### Verification

Check dependency status before processing:

```python
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:

```python
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`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/dependencies.py) | Defines EPUB dependency group and installation logic |
| [`book_to_skill/config.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/config.py) | Maps module names to PyPI package specifications |
| [`book_to_skill/parsers/epub.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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`](https://github.com/virgiliojr94/book-to-skill/blob/main/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.