pdftotext-fallback
Recover PDF text extraction when read_file returns binary data by using pdftotext via shell
- License 许可
- MIT
- 最近更新
- 2026-04-06
- Stars
- ★ 0
- Forks
- 0
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
zip-export-deliverable
Ensures codebase deliverables are properly exported as ZIP archives through a dedicated finalization step
zip-deliverable-finalization
Ensure codebase deliverables are properly packaged as ZIP exports in a dedicated final step
zero-iteration-failure-analysis
Identify and handle agent failures with 0 iterations as pre-execution system issues
write-file-fallback-report
Generate professional documents using write_file when primary data sources fail, leveraging embedded domain knowledge instead of external retrieval
fallback-doc-with-delegation
Generate professional documents after tool failures using shell_agent for complex formats or write_file for simple text/markdown
context-anchored-fallback-report
Generate documents with write_file when retrieval tools fail, with explicit guardrails against task context drift