---
name: pdftotext-fallback-5d2ce16592e8
description: Recover PDF text extraction when read_file returns binary data by using pdftotext via shell
---

# pdftotext Fallback for PDF Text Extraction

## When to Use

Apply this pattern when:
- `read_file` on a PDF returns binary/image data instead of readable text
- Python-based PDF extraction (PyMuPDF, pdfplumber, etc.) in `execute_code_sandbox` fails or returns garbled content
- You need reliable text extraction from PDF files as a recovery strategy

## Why This Works

The `pdftotext` utility (from poppler-utils) is a mature, command-line tool that handles many PDF edge cases that confuse Python libraries or the `read_file` tool. It's pre-installed on most Linux systems and provides consistent, reliable text extraction.

## Steps

### Step 1: Detect the Failure

Recognize extraction failure when:
- `read_file` returns binary content, image data, or garbled text
- Error messages indicate encoding issues or unsupported formats
- Python PDF libraries in sandbox fail with import errors or extraction failures

### Step 2: Use pdftotext via run_shell

**Extract to stdout** (recommended for quick extraction):

```bash
pdftotext /path/to/file.pdf -
```

The `-` argument outputs directly to stdout for easy capture in your tool response.

**Example:**
```bash
run_shell("pdftotext document.pdf -")
```

### Step 3: Handle Complex PDFs

**Preserve layout** (maintains original formatting):
```bash
pdftotext -layout /path/to/file.pdf -
```

**Extract to a file** (for large PDFs):
```bash
pdftotext /path/to/file.pdf /path/to/output.txt
```
Then read the output file with `read_file`.

**Handle encoded text:**
```bash
pdftotext -enc UTF-8 /path/to/file.pdf -
```

### Step 4: Verify and Continue

- Check the extracted text for completeness
- If text is still garbled, the PDF may be image-based (scanned) - consider OCR tools
- Proceed with your task using the extracted text

## Code Examples

**Basic extraction:**
```bash
# Simple text extraction
text = run_shell("pdftotext document.pdf -")
```

**With error handling:**
```bash
# Try extraction, check for success
result = run_shell("pdftotext document.pdf - && echo 'SUCCESS' || echo 'FAILED'")
```

**Multi-page PDF with layout:**
```bash
# Preserve tables and formatting
text = run_shell("pdftotext -layout document.pdf -")
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `pdftotext: command not found` | Install poppler-utils: `apt-get install poppler-utils` |
| Garbled/special characters | Try `-enc UTF-8` or `-enc ASCII7` |
| Missing formatting | Use `-layout` flag |
| Scanned PDF (no text) | Requires OCR (e.g., tesseract), not text extraction |
| Large PDF timeout | Extract to file instead of stdout |

## Limitations

- Does not work on image-only (scanned) PDFs without embedded text
- May lose complex formatting, tables, or embedded objects
- Requires poppler-utils to be installed (common on Linux, may need installation on other systems)

## Related Tools

- `pdfinfo`: Get PDF metadata (pages, size, etc.)
- `pdftoppm`: Convert PDF pages to images
- `tesseract`: OCR for scanned PDFs

---
Source attribution: xyliu-cs
Original project: https://github.com/xyliu-cs/OpenSpace-GDPval/blob/af1b40a42167d09c30b3a63000aa14ace4c1e229/gdpval_bench/skills/pdftotext-fallback/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Dave AI.

## Upstream license notice

MIT License

Copyright (c) 2026 ✨Data Intelligence Lab@HKU✨

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Dave AI resource metadata

Creator / publisher: xyliu-cs
Original project: https://github.com/xyliu-cs/OpenSpace-GDPval/blob/af1b40a42167d09c30b3a63000aa14ace4c1e229/gdpval_bench/skills/pdftotext-fallback/SKILL.md
Attribution basis: Source repository record

Fields of work: Content & Media, Data & Analytics, Development & Engineering, Education & Research
Roles: Backend Developer, Data Analyst, Data Scientist, Researcher, Technical Writer
Specialties: API, Backend
Tools: Pdftotext, Poppler Utils
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: ace6262c1b7c38e25cae31a30928cdeedfe5b65d573a5a84dad79431ac0d763d