Skip to content

Installation

Requirements

Requirement Version Notes
Python 3.13 or 3.14+ requires-python = ">=3.13" — see Supported runtimes
uv current Dependency and environment manager
mise current Runs the project tasks and tool versions

Supported runtimes

Runtime Support
CPython 3.13 GIL-enabled build only; the free-threaded 3.13t build is not supported
CPython 3.14 Supported, including the free-threaded 3.14t build (Ubuntu, macOS, Windows)
CPython 3.15-dev Best-effort

Core installs and runs on all of the above. Individual extras can be narrower: some publish wheels for one interpreter family only (a Rust abi3 extension does not load on a free-threaded build; onnxruntime has no free-threaded macOS or Windows wheel at all). See Interpreter and platform availability before choosing a free-threaded host for a workflow that needs a specific engine.

GPU torch

OCR backends need torch, and the PyPI Windows/Linux wheels are CPU builds — so an OCR backend on a CUDA host would silently run on the CPU. When torch or torchvision is resolved from this project (a checkout, or a downstream project that copies the index block from pyproject.toml), uv therefore pulls them from the PyTorch cu128 index automatically:

Platform torch source Device
Windows, Linux download.pytorch.org/whl/cu128 CUDA (cu128; older GPUs may need a different CUDA — override the index in your own pyproject.toml)
macOS PyPI (index excluded by marker) CPU + MPS

On a GPU host the CUDA driver still has to match the wheel — the index selects the CUDA build, not the driver.

The project's torch version ranges are unchanged by this — the index only provides the CUDA variant. uv tool install/uvx installs of the CLI carry no torch at all (torch arrives with the OCR extras), so plain CLI installs are unaffected.

From PyPI

Add the dependency with uv:

uv add parsecraft
uv run parsecraft backends

Or with pip:

pip install parsecraft
parsecraft backends

Current version on PyPI.

Extras

The base install is self-sufficient for the routing pipeline: the System One judge client, the OCR-need classifier, the fast liteparse parser, openpyxl for spreadsheets, and the pypandoc wrapper all ship in the core. Extras add the heavyweight or licence-isolated engines:

  • parsecraft[docling] — layout-aware parsing.
  • parsecraft[pymupdf] — PyMuPDF extraction for PDF and office documents (AGPL-3.0-or-commercial).
  • parsecraft[mineru] — the native MinerU2.5 VLM backend (Apache-2.0 checkpoint, no mineru package).
  • parsecraft[pdf-full] — the full PDF stack in one name: PyMuPDF and the native VLM backend.
  • parsecraft[ocr] — the GPU OCR/VLM backends (torch, transformers).
  • parsecraft[vllm] — the vLLM accelerator (Linux/WSL2 only).
  • parsecraft[web] — the trafilatura HTML backend.

pandoc conversions need no extra but do need the pandoc binary on the host (install it with your package manager); the backend is eligible only where the engine exists. Judge credentials come from the environment (TYPESAFE_API_KEY, OPENCODE_API_KEY) — see Backends for the per-backend extras table and Steer the auto-backend selector for the flags themselves.

No base install converts an office document. Word (.docx) has three separate routes: parsecraft[docling] — headings, tables, and reading order, conversion-verified 2026-10-17 — parsecraft[pymupdf] (AGPL), or the pandoc binary above. The same split applies to .pptx; .xlsx needs no extra (openpyxl is core). Legacy Word 97-2003 binary (.doc) has one route: parsecraft[docling] reads it natively in Rust, with no LibreOffice and no model download.

Conditional-licence extras

One extra carries licence terms you are consenting to by installing it — it is neither a core nor a dev dependency and is opt-in:

  • parsecraft[pymupdf] — PyMuPDF, AGPL-3.0-or-commercial.

Read the full statement on the Backends page before installing.

The mineru extra was in this category until 2026-10-26: parsecraft now runs the MinerU2.5 checkpoint itself (Apache-2.0 weights, MIT code), and the mineru package with its conditional code licence — and its onnxruntime-carrying GIL-builds-only install constraint — is no longer a dependency. See ADR-0007's amendment.

Upgrading

Releases are CalVer (YYYY.M.N); pin an exact version when you depend on anything beyond the CLI. The table lists the changes that need work on your side — if you do not touch the named surface, a plain upgrade is safe.

If you use Changed in What to do
"docling" in installed_extras 2026.10.15 only Pin parsecraft==2026.10.14, or upgrade to >=2026.10.16. That single release installed docling-rs while probing for the old docling distribution, so parsecraft[docling] reported the extra as absent and the docling backend was ineligible for every source. In auto mode that is silent — the candidate is dropped before planning and no surface names it — while a --backend docling pin fails loudly with pinned backend 'docling' is not eligible for this source.
parsecraft.backends.docling.libreoffice (LIBREOFFICE_ENV, find_libreoffice_cmd, resolve_libreoffice_cmd, configure_libreoffice_env, LibreOfficeUnavailableError) 2026.10.16 Copy the helpers you need, or pin parsecraft==2026.10.15. The module is gone, not renamed; the backend stopped calling it in 2026.10.15 and no declared format needs LibreOffice.
DOCLING_LIBREOFFICE_CMD 2026.10.15 Nothing — the backend stopped reading it. Office formats are already parsed natively by docling-rs and the variable has no effect.
OCR being implicitly off next release Nothing, unless you relied on it. OCR permission is now derived from EnvironmentInfo.ocr_backends — the registered OCR-family backends whose dependency group is installed or whose engine is usable — instead of an ocr- extra-name prefix that no extra ever carried. So installing parsecraft[ocr] or parsecraft[surya] now permits OCR where it previously never did, and on a host with no OCR harness an image-only page is planned onto an installed OCR-capable parser (docling, marker, mineru) with intent=ocr rather than degrading to native. Permission is not capability: whether a permitted backend runs is still decided by the existing GPU and VRAM gate, so installing [ocr] on a host without a usable GPU changes nothing. Pass --no-ocr to keep the old behaviour.
convert stderr on OCR pages next release Nothing — additive. A degraded-empty-output quality signal, and a matching stderr line, now appears when an OCR-capable parser returns no blocks for a page that needed OCR and reported no diagnosis of its own; the constant DEGRADED_EMPTY_OUTPUT_CODE is exported from parsecraft.pipeline. Exit codes are unchanged: a document where every pass failed still exits 1 on the distinct pipeline-all-passes-failed, and an adapter that explained itself (for example docling with OCR models missing) reports through its own page diagnostic instead.
--backend docling with --backend-option next release Fix the option name, or stop passing it. The docling adapter now honours --backend-option — until now it accepted the flag and discarded it — so a key it does not know is rejected with exit 1 and the accepted list, where it used to be ignored in silence. This only bites a script that already pinned --backend docling and passed a key nothing read: the flag requires --backend, so auto-mode callers cannot reach it. The other backends still ignore unknown keys (pc-23b); do not read their silence as acceptance.

Per-release behaviour changes are in the GitHub release body. The body is written by an opt-in AI step; when that step is not configured it carries only the compare link, which still lists every commit and its message.

From source

Use a checkout when contributing or testing unreleased changes. Clone and sync:

git clone https://github.com/jr2804/parsecraft.git
cd parsecraft
uv sync --dev
uv run parsecraft backends

Or use mise, which also installs the pinned tool versions:

git clone https://github.com/jr2804/parsecraft.git
cd parsecraft
mise dev
uv run parsecraft backends

mise dev writes the virtual environment created by uv. Activate it with source .venv/bin/activate (POSIX) or .venv\Scripts\activate (Windows) if you prefer parsecraft over uv run parsecraft.

Verify the install

uv run parsecraft --version
uv run parsecraft backends

parsecraft backends prints No backends registered. on a fresh checkout — no third-party backend is installed by default. Install the example backend to see discovery working:

uv pip install examples/third_party_backend
uv run parsecraft backends
# example-echo             cpu              text