yfedoseev/pdf_oxide
GitHub: yfedoseev/pdf_oxide
基于Rust的高性能PDF处理库，提供文本提取、Markdown转换、图像提取和PDF编辑功能，比PyMuPDF快5倍且MIT许可。
Stars: 263 | Forks: 30
# PDF Oxide - 适用于 Python、Rust、CLI 和 AI 的最快 PDF 工具包
最快的 PDF 库，用于文本提取、图像提取和 Markdown 转换。Rust 核心配合 Python 绑定、WASM 支持、CLI 工具以及面向 AI 助手的 MCP 服务器。平均每个文档 0.8ms，比 PyMuPDF 快 5 倍，比 pypdf 快 15 倍。在 3,830 个真实 PDF 上达到 100% 通过率。MIT 许可。
[](https://crates.io/crates/pdf_oxide)
[](https://pypi.org/project/pdf_oxide/)
[](https://pypi.org/project/pdf-oxide/)
[](https://www.npmjs.com/package/pdf-oxide-wasm)
[](https://docs.rs/pdf_oxide)
[](https://github.com/yfedoseev/pdf_oxide/actions)
[](https://opensource.org/licenses)
## 快速开始
### Python
```
from pdf_oxide import PdfDocument
doc = PdfDocument("paper.pdf")
text = doc.extract_text(0)
chars = doc.extract_chars(0)
markdown = doc.to_markdown(0, detect_headings=True)
```
```
pip install pdf_oxide
```
### Rust
```
use pdf_oxide::PdfDocument;
let mut doc = PdfDocument::open("paper.pdf")?;
let text = doc.extract_text(0)?;
let images = doc.extract_images(0)?;
let markdown = doc.to_markdown(0, Default::default())?;
```
```
[dependencies]
pdf_oxide = "0.3"
```
### CLI
```
pdf-oxide text document.pdf
pdf-oxide markdown document.pdf -o output.md
pdf-oxide search document.pdf "pattern"
pdf-oxide merge a.pdf b.pdf -o combined.pdf
```
```
brew install yfedoseev/tap/pdf-oxide
```
### MCP 服务器 (用于 AI 助手)
```
# 安装
brew install yfedoseev/tap/pdf-oxide # includes pdf-oxide-mcp
# 在 Claude Desktop / Claude Code / Cursor 中配置
{
"mcpServers": {
"pdf-oxide": { "command": "crgx", "args": ["pdf_oxide_mcp@latest"] }
}
}
```
## 为什么选择 pdf_oxide?
- **快速** — 平均每个文档 0.8ms，比 PyMuPDF 快 5 倍，比 pypdf 快 15 倍，比 pdfplumber 快 29 倍
- **可靠** — 在 3,830 个测试 PDF 上达到 100% 通过率，零 panic，零超时
- **功能完整** — 集文本提取、图像提取、PDF 创建和编辑于一体
- **多平台** — 支持 Rust、Python、JavaScript/WASM、CLI 以及面向 AI 助手的 MCP 服务器
- **宽松许可证** — MIT / Apache-2.0 — 可在商业和开源项目中自由使用
## 性能
基于来自三个独立公开测试套件（veraPDF、Mozilla pdf.js、DARPA SafeDocs）的 3,830 个 PDF 进行基准测试。仅测试文本提取库（无 OCR）。单线程，60 秒超时，无预热。
### Python 库
| 库 | 平均值 | p99 | 通过率 | 许可证 |
|---------|------|-----|-----------|---------|
| **PDF Oxide** | **0.8ms** | **9ms** | **100%** | **MIT** |
| PyMuPDF | 4.6ms | 28ms | 99.3% | AGPL-3.0 |
| pypdfium2 | 4.1ms | 42ms | 99.2% | Apache-2.0 |
| pymupdf4llm | 55.5ms | 280ms | 99.1% | AGPL-3.0 |
| pdftext | 7.3ms | 82ms | 99.0% | GPL-3.0 |
| pdfminer | 16.8ms | 124ms | 98.8% | MIT |
| pdfplumber | 23.2ms | 189ms | 98.8% | MIT |
| markitdown | 108.8ms | 378ms | 98.6% | MIT |
| pypdf | 12.1ms | 97ms | 98.4% | BSD-3 |
### Rust 库
| 库 | 平均值 | p99 | 通过率 | 文本提取 |
|---------|------|-----|-----------|-----------------|
| **PDF Oxide** | **0.8ms** | **9ms** | **100%** | **内置** |
| oxidize_pdf | 13.5ms | 11ms | 99.1% | 基础 |
| unpdf | 2.8ms | 10ms | 95.1% | 基础 |
| pdf_extract | 4.08ms | 37ms | 91.5% | 基础 |
| lopdf | 0.3ms | 2ms | 80.2% | 无内置提取 |
### 文本质量
在整个语料库中，与 PyMuPDF 和 pypdfium2 相比达到 99.5% 的文本一致性。PDF Oxide 从"困难"文件中提取的文本量比遗漏的量多 7–10 倍（相比任何竞争对手）。
### 语料库
| 套件 | PDFs | 通过率 |
|-------|-----:|----------:|
| [veraPDF](https://github.com/veraPDF/veraPDF-corpus) (PDF/A 合规性) | 2,907 | 100% |
| [Mozilla pdf.js](https://github.com/mozilla/pdf.js/tree/master/test/pdfs) | 897 | 99.2% |
| [SafeDocs](https://github.com/pdf-association/safedocs) (针对性边缘情况) | 26 | 100% |
| **总计** | **3,830** | **100%** |
在所有有效 PDF 上达到 100% 通过率 —— 语料库中 7 个未通过的文件是故意损坏的测试夹具（缺少 PDF 头、模糊破坏的目录、无效的 xref 流）。
## 功能
| 提取 | 创建 | 编辑 |
|---------|--------|------|
| 文本与布局 | 文档 | 注释 |
| 图像 | 表格 | 表单域 |
| 表单 | 图形 | 书签 |
| 注释 | 模板 | 链接 |
| 书签 | 图像 | 内容 |
## Python API
```
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
print(f"Pages: {doc.page_count()}")
print(f"Version: {doc.version()}")
# 1. 范围提取 (v0.3.14)
# 仅从特定区域提取： (x, y, width, height)
header = doc.within(0, (0, 700, 612, 92)).extract_text()
# 2. 单词级提取 (v0.3.14)
words = doc.extract_words(0)
for w in words:
print(f"{w.text} at {w.bbox}")
# Access individual characters in the word
# print(w.chars[0].font_name)
# 3. 行级提取 (v0.3.14)
lines = doc.extract_text_lines(0)
for line in lines:
print(f"Line: {line.text}")
# 4. 表格提取 (v0.3.14)
tables = doc.extract_tables(0)
for table in tables:
print(f"Table with {table.row_count} rows")
# 5. 传统提取
text = doc.extract_text(0)
chars = doc.extract_chars(0)
```
### 表单域
```
# 提取表单字段
fields = doc.get_form_fields()
for f in fields:
print(f"{f.name} ({f.field_type}) = {f.value}")
# 填写并保存
doc.set_form_field_value("employee_name", "Jane Doe")
doc.set_form_field_value("wages", "85000.00")
doc.save("filled.pdf")
```
## Rust API
```
use pdf_oxide::PdfDocument;
fn main() -> Result<(), Box> {
let mut doc = PdfDocument::open("paper.pdf")?;
// Extract text
let text = doc.extract_text(0)?;
// Character-level extraction
let chars = doc.extract_chars(0)?;
// Extract images
let images = doc.extract_images(0)?;
// Vector graphics
let paths = doc.extract_paths(0)?;
Ok(())
}
```
### 表单域 (Rust)
```
use pdf_oxide::editor::{DocumentEditor, EditableDocument, SaveOptions};
use pdf_oxide::editor::form_fields::FormFieldValue;
let mut editor = DocumentEditor::open("w2.pdf")?;
editor.set_form_field_value("employee_name", FormFieldValue::Text("Jane Doe".into()))?;
editor.save_with_options("filled.pdf", SaveOptions::incremental())?;
```
## 安装
### Python
```
pip install pdf_oxide
```
提供 Linux、macOS 和 Windows 的 wheel 包。支持 Python 3.8–3.14。
### Rust
```
[dependencies]
pdf_oxide = "0.3"
```
### JavaScript/WASM
```
npm install pdf-oxide-wasm
```
```
const { WasmPdfDocument } = require("pdf-oxide-wasm");
```
### CLI
```
brew install yfedoseev/tap/pdf-oxide # Homebrew (macOS/Linux)
cargo install pdf_oxide_cli # Cargo
cargo binstall pdf_oxide_cli # Pre-built binary via cargo-binstall
```
### MCP 服务器
```
brew install yfedoseev/tap/pdf-oxide # Included with CLI in Homebrew
cargo install pdf_oxide_mcp # Cargo
```
## CLI
提供 22 条命令，可直接从终端处理 PDF：
```
pdf-oxide text report.pdf # Extract text
pdf-oxide markdown report.pdf -o report.md # Convert to Markdown
pdf-oxide html report.pdf -o report.html # Convert to HTML
pdf-oxide info report.pdf # Show metadata
pdf-oxide search report.pdf "neural.?network" # Search (regex)
pdf-oxide images report.pdf -o ./images/ # Extract images
pdf-oxide merge a.pdf b.pdf -o combined.pdf # Merge PDFs
pdf-oxide split report.pdf -o ./pages/ # Split into pages
pdf-oxide watermark doc.pdf "DRAFT" # Add watermark
pdf-oxide forms w2.pdf --fill "name=Jane" # Fill form fields
```
不带参数运行 `pdf-oxide` 可进入交互式 REPL 模式。使用 `--pages 1-5` 处理特定页面，使用 `--json` 获取机器可读的输出。
## MCP 服务器
`pdf-oxide-mcp` 让 AI 助手（Claude、Cursor 等）可以通过 [Model Context Protocol](https://modelcontextprotocol.io/) 在本地从 PDF 中提取内容。
添加到您的 MCP 客户端配置中：
```
{
"mcpServers": {
"pdf-oxide": { "command": "crgx", "args": ["pdf_oxide_mcp@latest"] }
}
}
```
该服务器暴露了一个 `extract` 工具，支持文本、Markdown 和 HTML 输出格式，并可选页面范围和图像提取。所有处理均在本地运行 —— 文件不会离开您的设备。
## 从源码构建
```
# 克隆并构建
git clone https://github.com/yfedoseev/pdf_oxide
cd pdf_oxide
cargo build --release
# 运行测试
cargo test
# 构建 Python 绑定
maturin develop
```
## 文档
- **[完整文档](https://pdf.oxide.fyi)** - 完整文档站点
- **[入门指南 (Rust)](https://pdf.oxide.fyi/docs/getting-started/rust)** - Rust 指南
- **[入门指南 (Python)](https://pdf.oxide.fyi/docs/getting-started/python)** - Python 指南
- **[入门指南 (WASM)](https://pdf.oxide.fyi/docs/getting-started/javascript)** - 浏览器和 Node.js 指南
- **[入门指南 (CLI)](https://pdf.oxide.fyi/docs/getting-started/cli)** - CLI 指南
- **[入门指南 (MCP)](https://pdf.oxide.fyi/docs/getting-started/mcp)** - 面向 AI 助手的 MCP 服务器
- **[API 文档](https://docs.rs/pdf_oxide)** - 完整 Rust API 参考
- **[性能基准测试](https://pdf.oxide.fyi/docs/performance)** - 完整基准测试方法和结果
## 使用场景
- **RAG / LLM 流水线** — 将 PDF 转换为干净的 Markdown，用于 LangChain、LlamaIndex 或任何框架的检索增强生成
- **AI 助手** — 通过 MCP 服务器让 Claude、Cursor 或任何兼容 MCP 的工具直接访问 PDF
- **大规模文档处理** — 在几秒钟内从数千个 PDF 中提取文本、图像和元数据
- **数据提取** — 从表单、表格和布局中提取结构化数据
- **学术研究** — 解析论文、提取引用和处理大型语料库
- **PDF 生成** — 以编程方式创建发票、报告、证书和模板化文档
- **PyMuPDF 替代方案** — MIT 许可、快 5 倍、无 AGPL 限制
## 许可证
根据您的选择，双重许可于 [MIT](LICENSE-MIT) 或 [Apache-2.0](LICENSE-APACHE)。与 AGPL 许可的替代方案不同，pdf_oxide 可以在任何项目中自由使用 —— 无论是商业还是开源 —— 无 Copyleft 限制。
## 引用
```
@software{pdf_oxide,
title = {PDF Oxide: Fast PDF Toolkit for Rust and Python},
author = {Yury Fedoseev},
year = {2025},
url = {https://github.com/yfedoseev/pdf_oxide}
}
```
**Rust** + **Python** + **WASM** + **CLI** + **MCP** | MIT/Apache-2.0 | 3,830 个 PDF 上 100% 通过率 | 平均 0.8ms | 比 PyMuPDF 快 5 倍 | v0.3.14
标签：AI辅助, Markdown转换, MCP服务器, OCR替代, PDF处理, PDF生成, PDF编辑, Rust库, Rust绑定, WebAssembly, 可视化界面, 图像提取, 开源库, 搜索引擎爬虫, 数据提取, 文本提取, 文档工具, 文档结构分析, 文档解析, 逆向工具, 通知系统, 通知系统, 通知系统