pdftotext-fallback
Recover PDF text extraction when read_file returns binary data by using pdftotext via shell
- License 许可
- MIT
- 所属仓库
- HKUDS/AgentPilot
- 最近更新
- 2026-11-12
- Stars
- ★ 8.0k
- Forks
- 944
01 前言 Front Matter
- name
- pdftotext-fallback
- description
- Recover PDF text extraction when read_file returns binary data by using pdftotext via shell
02 资源文件 1
- 其他.skill_id32 B
03 SKILL.md 正文
pdftotext Fallback for PDF Text Extraction
When to Use
Apply this pattern when:
read_fileon a PDF returns binary/image data instead of readable text- Python-based PDF extraction (PyMuPDF, pdfplumber, etc.) in
execute_code_sandboxfails 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_filereturns 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):
pdftotext /path/to/file.pdf -
The - argument outputs directly to stdout for easy capture in your tool response.
Example:
run_shell("pdftotext document.pdf -")
Step 3: Handle Complex PDFs
Preserve layout (maintains original formatting):
pdftotext -layout /path/to/file.pdf -
Extract to a file (for large PDFs):
pdftotext /path/to/file.pdf /path/to/output.txt
Then read the output file with read_file.
Handle encoded text:
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:
# Simple text extraction
text = run_shell("pdftotext document.pdf -")
With error handling:
# Try extraction, check for success
result = run_shell("pdftotext document.pdf - && echo 'SUCCESS' || echo 'FAILED'")
Multi-page PDF with layout:
# 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 imagestesseract: OCR for scanned PDFs
04 同仓库更多 Skills
agentpilot
Set up AgentPilot and use its single entry to prepare missing inputs and run configured RSI experiments. Use when the user requests AgentPilot installation or work with AgentPilot.
remember
Review auto-memory entries and propose promotions to OPENSPACE.md, OPENSPACE.local.md, or retained auto-memory topics; detect duplicates, stale facts, conflicts, and ambiguous entries before making changes.
skill-discovery
Search reusable OpenSpace skills locally, and browse cloud packages step by step when a cloud skill may help. Reusing proven skills saves tokens, improves reliability, and extends your capabilities beyond built-in tools.
delegate-task
Delegate tasks to OpenSpace — a full-stack autonomous worker for coding, DevOps, web research, and desktop automation, backed by an extensive MCP tool and skill library. Skills auto-improve through use, reducing token consumption over time. A cloud community lets agents share and collectively evolve reusable skills.
write-special-chars-ts-check
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, plus a reliable TypeScript type-checking step that filters output to only the newly-written files to avoid being misled by pre-existing errors.
write-special-chars-readback
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, with mandatory post-write verification via read_file and cleanup of /tmp helper scripts.