# What Fallback Parsers Does Book-to-Skill Use for PDF Files?

> Discover Book-to-Skill's PDF fallback parsers: Docling, pdftotext, pypdf, and pdfminer.six. Ensure robust text extraction for diverse documents.

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

---

**Book-to-Skill employs a four-tier progressive fallback chain for PDF text extraction, attempting Docling for technical layout-aware parsing, then cascading through pdftotext, pypdf, and finally pdfminer.six to ensure robust parsing across different document types and dependency configurations.**

Book-to-Skill is an open-source framework that transforms technical books into structured skill extraction pipelines. When processing PDF documents, the project implements a resilient multi-layered extraction strategy in [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) that automatically cascades through multiple parsing engines—managed by the orchestration logic in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) (lines 850-894)—to maximize text recovery success rates.

## The Four-Tier PDF Extraction Chain

The extraction logic resides in [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py), where four distinct parsers are implemented as separate utility functions. The system attempts each parser in sequence until one returns usable text content.

### Docling (Layout-Aware Technical Parsing)

When users specify `--mode technical`, Book-to-Skill first attempts extraction using **Docling**, a layout-aware parser that preserves document structure. The function `extract_with_docling` (lines 45-68 in [`parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/parsers/pdf.py)) handles this specialized parsing. If Docling fails to produce output or is unavailable, the system automatically falls back to the standard text extraction path.

### pdftotext (Primary Text Extraction)

For standard text mode operations, Book-to-Skill prioritizes `pdftotext`, the Poppler command-line utility. The `extract_with_pdftotext` function (lines 76-88 in [`parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/parsers/pdf.py)) wraps this system tool, which provides fast, high-quality text extraction for properly formatted PDFs. This represents the primary extraction method when operating in text mode.

### pypdf (First Fallback)

When `pdftotext` is unavailable on the system or returns empty output, Book-to-Skill automatically retries using **pypdf**, a pure Python library. The `extract_with_pypdf` function (lines 12-30 in [`parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/parsers/pdf.py)) handles this fallback layer, providing a dependency-light alternative that works without external system binaries.

### pdfminer.six (Final Fallback)

If both `pdftotext` and `pypdf` fail to extract usable text, the system makes a final attempt using **pdfminer.six**. The `extract_with_pdfminer` function (lines 33-42 in [`parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/parsers/pdf.py)) implements this last-resort parser, which specializes in extracting text from complex or malformed PDF structures that defeat simpler parsers.

## How the Fallback Logic Works

The central orchestration logic in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) manages the progressive chain by checking parser availability and output quality. The decision flow follows this priority:

- **Technical mode** users get Docling first, then standard text parsers
- **Text mode** attempts `pdftotext` → `pypdf` → `pdfminer.six`

Each attempt verifies that the extracted content contains actual text rather than whitespace or control characters before accepting the result. If a parser returns empty output, the system immediately proceeds to the next fallback option.

## Handling Edge Cases: Image-Only PDFs

Before initiating the full extraction chain, Book-to-Skill checks for image-only PDFs using the `looks_image_only` helper function in [`parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/parsers/pdf.py). This validation prevents wasted processing cycles on scanned documents that contain no extractable text layer, aborting early with an informative error message when detected.

## Practical Usage Examples

### Basic Text Mode Extraction

```python
from book_to_skill.utils import extract_single_file
from pathlib import Path

pdf_path = Path("my_book.pdf")
result = extract_single_file(
    pdf_path, 
    extraction_mode="text", 
    install_mode="no"
)

print(result["text"])      # Extracted content

print(result["method"])    # "pdftotext", "pypdf", or "pdfminer"

```

### Technical Mode with Layout Awareness

```python
result = extract_single_file(
    pdf_path, 
    extraction_mode="technical", 
    install_mode="no"
)

print(result["method"])    # "docling" if successful, 

                           # otherwise falls back to text parsers

```

### Direct Fallback Parser Invocation

```python
from book_to_skill.parsers.pdf import extract_with_pypdf

text = extract_with_pypdf("my_book.pdf")
print(text)   # Returns None if pypdf unavailable; 

              # otherwise returns cleaned text

```

## Summary

- **Book-to-Skill** implements a four-tier fallback parser chain in [`book_to_skill/parsers/pdf.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/parsers/pdf.py) to maximize PDF extraction reliability.
- The hierarchy runs: **Docling** (technical mode) → **pdftotext** → **pypdf** → **pdfminer.six**.
- Orchestration logic in [`book_to_skill/utils.py`](https://github.com/virgiliojr94/book-to-skill/blob/main/book_to_skill/utils.py) (lines 850-894) automatically manages the cascade based on mode selection and parser availability.
- The `looks_image_only` check prevents processing on scanned image PDFs.
- Each parser is exposed as a discrete function, allowing direct invocation when specific extraction behavior is required.

## Frequently Asked Questions

### What determines which fallback parser Book-to-Skill selects?

The selection depends on the `extraction_mode` parameter and system dependencies. Technical mode prioritizes Docling, while text mode prefers `pdftotext`. If the primary parser is unavailable or returns empty output, the system automatically proceeds to the next fallback in the chain until text is successfully extracted or all options are exhausted.

### Can I force Book-to-Skill to use a specific PDF parser?

Yes, you can import and invoke individual parser functions directly from `book_to_skill.parsers.pdf`. For example, calling `extract_with_pypdf()` bypasses the automatic chain logic and attempts extraction using only that specific library, returning `None` if the dependency is missing or extraction fails.

### Does Book-to-Skill handle scanned PDFs without text layers?

The system attempts to detect image-only PDFs using the `looks_image_only` function before extraction begins. If a document is identified as containing only images without an embedded text layer, Book-to-Skill aborts the process early with an informative error rather than attempting the full fallback chain on unextractable content.

### What is the difference between technical mode and text mode for PDF parsing?

Technical mode activates Docling, which preserves document layout and structure ideal for technical books with complex formatting. Text mode uses the `pdftotext` → `pypdf` → `pdfminer.six` chain focused on raw text extraction, offering faster processing for standard documents while maintaining reliability through multiple fallback options.