pdf-to-markdown is a PDF-to-Markdown converter purpose-built for AI Agents. Powered by MinerU, PaddleOCR, and Zhipu AI's state-of-the-art document parsing, it accurately extracts text, tables, formulas, images, and document structure — handling complex layouts from academic papers to technical reports with ease. No local GPU required, no API key needed (batteries-included with MinerU Agent). A single command turns any PDF into clean, structured Markdown. The go-to tool for AI Agents reading and processing PDFs.
- Multiple provider support: MinerU (VLM/Pipeline/Agent), PaddleOCR, Zhipu AI (lite/expert/prime)
- Zero-config ready — MinerU Agent requires no API key; smart auto-detection picks the best available provider
- Secure API key storage in encrypted credentials file (AES-256-GCM)
- Complex element parsing: text, images, tables, formulas, and more
- Structured JSON output, meaningful exit codes, and dry-run support
- Easy installation with one-click script for Linux/macOS/Windows
- Flexible configuration with extensive CLI options
- Built-in caching to avoid redundant API calls
- Duplicate detection based on file hash and URL
- Text: paragraphs, headings, lists, and other text content
- Images: automatic extraction and saving of document images
- Tables: intelligent table recognition and conversion to Markdown format
- Formulas: LaTeX formula recognition with formula numbering
- Layout: automatic document layout structure detection
Optimized for academic publications such as Arxiv papers.
Linux/macOS:
curl -fsSL https://raw.githubusercontent.com/Peng-YM/pdf-to-markdown/master/install.sh | bashFor alternative installation methods, see GitHub Releases or build from source.
For AI coding agents (Claude Code, Codex, etc.), install the agent skill so the agent automatically uses pdf-to-markdown whenever it needs to read a PDF:
npx skills add Peng-YM/pdf-to-markdownThe skill provides the agent with installation guidance, login workflow, usage patterns, best practices, and troubleshooting — no manual configuration needed.
For more development information, see CONTRIBUTING.md.
API keys are optional — MinerU Agent works out of the box with no setup. Add a key for higher quality or more daily capacity.
# Interactive: select provider and enter API key
pdf-to-markdown login
# Store API key for a specific provider
pdf-to-markdown login --provider paddleocr
pdf-to-markdown login --provider zhipu
pdf-to-markdown login --provider mineru
# Non-interactive: specify both provider and key
pdf-to-markdown login --provider paddleocr --api-key "your_api_key"
# List stored credentials
pdf-to-markdown login --list
# Delete a stored credential
pdf-to-markdown login --delete paddleocrAPI keys are stored in an AES-256-GCM encrypted file and never saved in plaintext.
export PADDLE_OCR_API_KEY="your_api_key"
export ZHIPU_API_KEY="your_api_key"
export MINERU_API_KEY="your_api_key" # Precision API only; Agent API needs no keyOr pass via --api-key / -k flag:
pdf-to-markdown parse -k "your_api_key" document.pdf- Application URL: https://mineru.net/apiManage/token
- Models: VLM (recommended), Pipeline, Agent (lightweight, no auth)
- Agent API: No token required, IP rate-limited, 10MB/20 pages max
- Precision API: 1,000 pages/day priority, ZIP output with images
- Application URL: https://aistudio.baidu.com/paddleocr
- Free quota: 20,000 pages per day
- Application URL: https://bigmodel.cn/usercenter/proj-mgmt/apikeys
- Note: Real-name authentication required
# Convert PDF to Markdown — no setup needed (uses MinerU Agent by default)
pdf-to-markdown parse document.pdf
# Optional: add an API key for higher quality or more capacity
pdf-to-markdown login
# Using Zhipu AI
pdf-to-markdown login --provider zhipu
pdf-to-markdown parse --provider zhipu/lite document.pdf
# Using MinerU VLM (best quality, requires token)
pdf-to-markdown login --provider mineru
pdf-to-markdown parse --provider mineru document.pdf
# Using MinerU Agent (lightweight, no auth needed)
pdf-to-markdown parse --provider mineru/agent document.pdf
# Using URL to download PDF directly
pdf-to-markdown parse https://example.com/document.pdf
# Using arxiv abs link (automatically converts to pdf link)
pdf-to-markdown parse https://arxiv.org/abs/2301.07041pdf-to-markdown parse \
--provider zhipu/expert \
--api-key "your_api_key" \
--pages 1-5,10 \
--output-dir ./output/ \
--json \
document.pdf# Extract metadata in human-readable format with local file
pdf-to-markdown metadata document.pdf
# Extract metadata using URL
pdf-to-markdown metadata https://example.com/document.pdf
# Extract metadata using arxiv abs link (automatically converts to pdf)
pdf-to-markdown metadata https://arxiv.org/abs/2301.07041
# Output in JSON format
pdf-to-markdown metadata document.pdf --json
# Save to file
pdf-to-markdown metadata document.pdf -o metadata.json# Basic usage with local file
pdf-to-markdown parse document.pdf
# Using URL to download PDF directly
pdf-to-markdown parse https://example.com/document.pdf
# Using arxiv abs link (automatically converts to pdf link)
pdf-to-markdown parse https://arxiv.org/abs/2301.07041
# Specify output directory
pdf-to-markdown parse document.pdf -o ./output/
# Specify page ranges
pdf-to-markdown parse document.pdf --pages 1-5,10,15-20
# Use different providers
pdf-to-markdown parse --provider paddleocr document.pdf
pdf-to-markdown parse --provider zhipu/lite document.pdf
pdf-to-markdown parse --provider zhipu/expert document.pdf
pdf-to-markdown parse --provider zhipu/prime document.pdf
pdf-to-markdown parse --provider mineru document.pdf
pdf-to-markdown parse --provider mineru/pipeline document.pdf
pdf-to-markdown parse --provider mineru/agent document.pdf
# Dry run to preview operations
pdf-to-markdown parse document.pdf --dry-run
# JSON output
pdf-to-markdown parse document.pdf --json
# Quiet mode (output only file path)
pdf-to-markdown parse document.pdf --quiet
# Overwrite existing output files
pdf-to-markdown parse document.pdf --overwrite
# Disable cache temporarily
PDF_TO_MARKDOWN_NO_CACHE=1 pdf-to-markdown parse document.pdf# Interactive: select provider and enter API key
pdf-to-markdown login
# Store API key for a specific provider (interactive key input)
pdf-to-markdown login --provider paddleocr
# Store API key non-interactively
pdf-to-markdown login --provider zhipu --api-key "your_api_key"
# List stored credentials
pdf-to-markdown login --list
# Delete stored credential
pdf-to-markdown login --delete paddleocr
# JSON output
pdf-to-markdown login --list --json# View cache status
pdf-to-markdown cache status
# View cache status in JSON format
pdf-to-markdown cache status --json
# Clear cache with confirmation
pdf-to-markdown cache clear
# Force clear cache without confirmation
pdf-to-markdown cache clear --forceThe tool automatically caches parsing results to avoid redundant API calls for the same PDF files or URLs, saving cost and time.
- File hash: SHA256 hash of local files as cache key
- URL hash: SHA256 hash of URLs as cache key
- Multi-dimensional caching: Cache key includes provider type and page ranges to prevent confusion between different configurations
- Image caching: Extracted images are also cached to speed up repeated parsing
Cache is stored in system standard cache directories:
- Linux:
~/.cache/pdf-to-markdown/ - macOS:
~/Library/Caches/pdf-to-markdown/ - Windows:
%LOCALAPPDATA%\\pdf-to-markdown\\cache\\
In some cases, you may want to bypass the cache and re-parse the file:
# Method 1: Set environment variable
PDF_TO_MARKDOWN_NO_CACHE=1 pdf-to-markdown parse document.pdf
# Method 2: Use true value
PDF_TO_MARKDOWN_NO_CACHE=true pdf-to-markdown parse document.pdfFor more development information, architecture design, and how to extend with new providers, see CONTRIBUTING.md.
This tool is optimized for automation and script integration:
- Structured output:
--jsonflag for JSON format output - Meaningful exit codes: 0=success, 1=failure, 2=usage error, 3=not found, 4=permission, 5=conflict
- Dry-run support:
--dry-runto preview operations - Quiet mode:
--quietsuitable for scripts and pipelines - Actionable errors: Includes error types and repair suggestions
- Comprehensive help: Extensive examples and clear parameter documentation
MIT