Skip to main content
DocVortex logo

DocVortex

Native document parsing. One structure, many outputs.

PyPI Python Downloads Monthly Downloads CI License: MIT

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 native-text 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.

DocVortex does not download models or perform PDF OCR. When OCR is required, it reports pdf_ocr_unsupported and asks you to download and install MinerU to process the document.

DocVortex pipeline: native documents become a unified representation, then Markdown, HTML, LaTeX, DOCX, EPUB, PDF or structured JSON.

PDF performance

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

Pipeline 0.4.25 python 0.5.10 rust Speedup Time reduction Peak RSS reduction
DocVortex public parse() 42.36 s 14.48 s 2.93× 65.82% 31.17%
MinerU Flash 44.50 s 14.44 s 3.08× 67.55% 29.84%
MinerU shared PDF processing 76.28 s 12.85 s 5.94× 83.16% 35.65%

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×.

The non-PDF optimization report records the original-to-final comparison, per-format timings, memory checks and remaining hotspots.

Quick start

Requires GIL-enabled CPython 3.11–3.14, pypdfium2 5.13.0 or newer, and ONNX Runtime 1.24.4 or newer (DirectML on Windows x64). On macOS, installation requires Apple Silicon and macOS 14 or newer; Intel Macs are no longer supported as of 0.6.0.

Version 0.6 keeps the Python SDK and CLI and requires its bundled Rust native extension. Releases contain ABI3 wheels for Linux x86_64/aarch64 (glibc 2.28+), Windows x86_64/ARM64, and macOS arm64. Pure Python wheels and source distributions are no longer published. PyPy and free-threaded Python are not supported. Starting with 0.6.1, DocVortex ignores the retired DOCVORTEX_BUILD_NATIVE and DOCVORTEX_COMPUTE_BACKEND variables, regardless of their values. The 0.6.0 package still rejects these variables. Existing 0.5 installations can stay on docvortex<0.6 while migrating.

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

Document family File extensions
PDF with native text or scanned pages .pdf
Word & rich text .doc, .docx, .rtf
Presentations .ppt, .pptx
Spreadsheets .xls, .xlsx, .csv, .tsv
OpenDocument .odt, .ods, .odp
E-books .epub
Web documents .html, .htm, .shtml
Web archives .mhtml, .mht
Open Fixed-layout Document .ofd

Outputs · 7 formats

Output --format / output_format
Markdown markdown
HTML html
LaTeX latex
Word document docx
EPUB e-book epub
PDF pdf
Structured JSON structured_content

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 defaults to pdf_structure="auto", which uses available Tagged PDF semantics and reading order, with Flash rules for uncovered content. pdf_structure="off" selects geometric parsing. The CLI accepts --pdf-structure auto|off. Original roles and block associations are recorded in docvortex_pdf_structure extensions. Tagged PDF usage
  • PDF classification under parse_mode="auto" first accepts sufficient structure evidence, then classifies the selected pages as a whole when needed. A txt result uses native parsing. An ocr result raises DocumentError with code pdf_ocr_unsupported and a MinerU download link. parse_mode="txt" forces native parsing. The CLI accepts --parse-mode auto|txt|ocr for PDF input.
  • PDF OCR: parse_mode="ocr" and --parse-mode ocr are retained for compatibility and always report pdf_ocr_unsupported for PDF input. Download and install MinerU for OCR. DocVortex does not install or invoke MinerU automatically.
  • Mixed PDFs: auto mode does not classify or switch backends per page. A selection classified as txt keeps native parsing even if it contains scanned pages. Use MinerU when those pages need OCR.
  • 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.
  • 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

Guide What you will find
Usage Stage APIs, PDF pages, classification, images and Bundles
Agent skill CLI and Python SDK workflows for agents; copy the entire skills/docvortex folder to reuse
Examples Local samples for PDF, Office, EPUB, web documents and OFD with a runnable demo
Metadata Source properties and per-format coverage
JSON protocol Document schemas, extensions and protocol migration
HTML protocol Semantic markers and round trips
Public SDK & migration Supported integration boundaries and the 0.4 upgrade
Rendering ownership DocVortex exports and MinerU-specific renderers

Development

See Repository architecture for directory responsibilities, the Python/Rust boundary, and native development commands. Source builds require the Rust toolchain pinned in rust-toolchain.toml and the platform's C/C++ linker.

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 --wheel

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.

Metadata

Release files for docvortex 0.6.25

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for docvortex 0.6.25
File Actions
docvortex-0.6.25-cp311-abi3-win_arm64.whl CPython 3.11 abi3 Windows ARM64 Details for docvortex-0.6.25-cp311-abi3-win_arm64.whl
docvortex-0.6.25-cp311-abi3-win_amd64.whl CPython 3.11 abi3 Windows x86-64 Details for docvortex-0.6.25-cp311-abi3-win_amd64.whl
docvortex-0.6.25-cp311-abi3-manylinux_2_28_x86_64.whl CPython 3.11 abi3 Linux glibc 2.28+ x86-64 Details for docvortex-0.6.25-cp311-abi3-manylinux_2_28_x86_64.whl
docvortex-0.6.25-cp311-abi3-manylinux_2_28_aarch64.whl CPython 3.11 abi3 Linux glibc 2.28+ ARM64 Details for docvortex-0.6.25-cp311-abi3-manylinux_2_28_aarch64.whl
docvortex-0.6.25-cp311-abi3-macosx_14_0_arm64.whl CPython 3.11 abi3 macOS 14.0+ ARM64 Details for docvortex-0.6.25-cp311-abi3-macosx_14_0_arm64.whl

Total release size: 26.8 MB

Release files / docvortex-0.6.25-cp311-abi3-win_arm64.whl

Download URL docvortex-0.6.25-cp311-abi3-win_arm64.whl
Size 5.2 MB
Tags CPython 3.11 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
290b7adcec0bef28220cb51523c04784c7643e8172e46fb8041988c2bd34b3ab
BLAKE2b-256 checksum
How to use checksums
f98d0abfa2e8db393bc66a0629338d659af2f68f5739d01e6f863bba6e27908b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / docvortex-0.6.25-cp311-abi3-win_amd64.whl

Download URL docvortex-0.6.25-cp311-abi3-win_amd64.whl
Size 5.4 MB
Tags CPython 3.11 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
fd9ef0066aeb48c4e24d244b7a46e8ead659e41a1f3e23694fa91eb507adbad1
BLAKE2b-256 checksum
How to use checksums
dd9ad903613e9b8a63e2cb02927f7f19028f6336727dc6d248a5f7fb98185f7f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / docvortex-0.6.25-cp311-abi3-manylinux_2_28_x86_64.whl

Download URL docvortex-0.6.25-cp311-abi3-manylinux_2_28_x86_64.whl
Size 5.5 MB
Tags CPython 3.11 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
a451eeb089eb9dbabe11c41f44240ad99c212466eaea697dc1ac75497affef28
BLAKE2b-256 checksum
How to use checksums
cb818d6485dfe3c3c0546bfd29f2612a8f674ccf43b94ad409e1dd8adb1ff90d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / docvortex-0.6.25-cp311-abi3-manylinux_2_28_aarch64.whl

Download URL docvortex-0.6.25-cp311-abi3-manylinux_2_28_aarch64.whl
Size 5.4 MB
Tags CPython 3.11 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
90586dd6d0ad02115cc7db5c51a944d1fdf2add1b3b144c3f04de298d40ec9e8
BLAKE2b-256 checksum
How to use checksums
642a3a798c9fd3ea33358e3b159393c1daf8a7b80b95aedcdfcbd7d6f8f4c7d7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / docvortex-0.6.25-cp311-abi3-macosx_14_0_arm64.whl

Download URL docvortex-0.6.25-cp311-abi3-macosx_14_0_arm64.whl
Size 5.3 MB
Tags CPython 3.11 abi3 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
180e1902e7bd26344bf55ed1adcef7f7b10772c74b6f134a4bf97ed4d1fc1aed
BLAKE2b-256 checksum
How to use checksums
136bcd338df9cc34723262ea8b7fc01a99f2594f6e84a16e056be961513f88c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for docvortex 0.6.25

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for docvortex-0.6.25-cp311-abi3-win_arm64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.6.25 This release

5 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page