DocVortex

Native document parsing. One structure, many outputs.

English · 简体中文

Performance · Quick start · Formats · Documentation

Documents in. Possibilities out.

DocVortex is a standalone Python engine for parsing and converting documents. It reads native text and document structure into a unified representation, then exports the result in the formats your workflow needs.

• Multi-format input — read text and scanned PDFs, Office files, OpenDocument files, EPUB, HTML, OFD, CSV and TSV.
• Parse once, export many times — reuse the same result for Markdown, HTML, LaTeX, DOCX, EPUB, PDF and structured JSON.
• Portable results — save document structure and image assets in a Bundle, then export again without the source file.
• Composable APIs — use the complete pipeline or integrate analysis, postprocessing and rendering separately.

Native parsing works without an OCR or VLM inference service. Use DocVortex directly through its CLI or Python SDK.

Scanned PDFs use local CPU OCR. The first OCR parse automatically downloads PP-DocLayoutV2 and PP-OCRv6 Tiny Det / Small Rec from Hugging Face, falling back to ModelScope, into ~/.docvortex/model/. The six model and configuration files total about 239 MB; a complete cache works offline.

PDF performance

Release 0.5.10 uses Rust acceleration: public parsing is 2.93× as fast as 0.4.25 on the tested corpus.

Same-machine warm-run comparison on 32 PDFs / 299 pages (31 PDFs for Flash). The existing 0.4.25 measurements are reused. For 0.5.10, each document is warmed once and timed five times in each of three balanced rounds; times sum the medians of the three per-document medians. RSS reductions are medians of per-document process-tree peak RSS reductions. MinerU results include improvements in both projects. The shared pipeline excludes model computation; excluding the extreme dense-table sample, its speedup is 2.87×.

Quick start

Requires Python 3.10–3.14.

Install

pip install docvortex

Command line

Convert a text PDF to Markdown:

docvortex convert report.pdf --format markdown --output output/report.md

Replace report.pdf with a local file in any supported input format. Use --format to choose the output; run docvortex convert --help for options. The root-level --log-level option controls loguru output and defaults to info. It must precede the command; DOCVORTEX_LOG_LEVEL=warning can also configure it.

Python

Parse a document once and export it twice:

import docvortex

result = docvortex.parse("report.pdf")
result.export("output/report.md", output_format="markdown")
result.export("output/report.docx", output_format="docx")

The result owns its document structure and assets, so further exports do not reopen or reparse the source. Existing output files are protected by default; use overwrite=True in Python or --overwrite in the CLI to replace them.

Supported formats

Native inputs · 20 formats

Outputs · 7 formats

PPT/PPTX and XLS/XLSX are input formats only. Structured JSON is an export format; the document JSON protocol separately defines the analysis and intermediate representations.

Save now, export later

A Bundle packages the parsed document and its image assets for reuse across processes or machines. Load it whenever you need another output format:

import docvortex

result = docvortex.parse("report.pdf")
result.save_bundle("output/report.bundle")

restored = docvortex.load_bundle("output/report.bundle")
restored.export("output/report.epub", output_format="epub")

The restored result works without the original file. See the usage guide for Bundle contents, asset handling and overwrite rules.

Need only the title, authors or other source properties? docvortex.extract_metadata() reads metadata without parsing the document body.

Choose the right workflow

• PDF parsing: parse_mode="auto" (default) classifies the selected PDF pages and chooses native text or local CPU OCR. Use parse_mode="txt" to force native parsing without classification or model downloads, or parse_mode="ocr" to force OCR. The CLI equivalent is --parse-mode auto|txt|ocr. Explicit modes apply only to PDF input.
• PDF OCR: layout supplies block regions and reading order; text blocks use Tiny Det / Small Rec. Display formulas, images, charts and seals retain screenshots. Inline formulas pass through ordinary text OCR. Tables contain spatially projected text and a screenshot, without structural cell recognition. No page orientation or unwarping model is used. A selected document uses one backend throughout.

If a mixed PDF is classified as txt but contains scanned pages, use parse_mode="ocr" (CLI: --parse-mode ocr) to OCR the entire selection.

• PDF classification: docvortex classify report.pdf returns txt or ocr without inference or networking. Metadata extraction and the low-level PdfModel.predict() native text API also remain offline. See model provenance.
• PDF export: PDF sources with page geometry default to block layout restoration, with selectable text and HTML-based tables; charts retain region images. Other sources and older results use semantic reflow. Use --pdf-layout original|reflow to select explicitly; fonts, line breaks and drawing instructions are not reproduced losslessly. See PDF output layout.

Documentation

Development

See Repository architecture for directory responsibilities, the Python/Rust boundary, and pure Python or native development commands.

From a local checkout:

uv venv
uv pip install -e ".[test,dev]"
uv run --no-project python -m pytest -q
uv run --no-project ruff check src
uv run --no-project ruff format --check src
uv build

Bug reports and contributions are welcome. When reporting a parsing issue, include a reproducible command and a sample document you can share in GitHub Issues.

License

DocVortex project code is released under the MIT License.