Docling MLX

Native MLX engines and Docling stage adaptors for Apple Silicon. Docling MLX is a community project, not an official Docling or IBM project. It requires Python 3.13 or newer and Docling 2.124 or newer.

Install

Until the first PyPI release, install from Git:

uv pip install "docling-mlx[standard] @ git+https://github.com/AtkinsChang/docling-mlx"

MLX itself is installed only on macOS arm64; elsewhere the package imports but its engines cannot run. The extras select how much of Docling comes with it:

What it provides

• The plugin stages need allow_external_plugins=True in the pipeline options.
• Docling has no picture-classification or chart-extraction factory. MlxStandardPdfPipeline, the only pipeline subclass in this package, installs those two stages after Docling's normal initialization. configure() does the same for a standard pipeline that was constructed with the MLX-owned picture and chart stages disabled.
• Enabled stages accept only the auto and mps accelerator selections and initialize their engine in the constructor; warmup=True additionally runs the engine's warmup path.
• The engines under docling_mlx.engines do not import Docling, and their predict() stays lazy for direct users.

Quick start

Convert a PDF with the Heron layout, TableFormerV2, and picture classification stages:

from pathlib import Path

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import ThreadedPdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

from docling_mlx.pipeline import MlxStandardPdfPipeline
from docling_mlx.stages.layout import (
    MlxLayoutObjectDetectionOptions,
    MlxObjectDetectionEngineOptions,
)
from docling_mlx.stages.picture_classification import MlxDocumentPictureClassifierOptions
from docling_mlx.stages.table_structure_v2 import MlxTableStructureV2Options

options = ThreadedPdfPipelineOptions(
    artifacts_path=Path(".artifacts"),
    allow_external_plugins=True,
    do_ocr=False,
    layout_options=MlxLayoutObjectDetectionOptions.from_preset(
        "layout_heron_default", engine_options=MlxObjectDetectionEngineOptions()
    ),
    do_table_structure=True,
    table_structure_options=MlxTableStructureV2Options(),
    do_picture_classification=True,
    picture_classification_options=MlxDocumentPictureClassifierOptions(),
)
result = DocumentConverter(
    allowed_formats=[InputFormat.PDF],
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_cls=MlxStandardPdfPipeline, pipeline_options=options
        )
    },
).convert("input.pdf")
print(result.document.export_to_markdown())

examples/std_pdf_pipeline_all_mlx.py and examples/mlx_pipeline/pipeline.py use this same shape. The latter adds OCRMac and a small JSON summary; it does not copy or subclass a Docling pipeline.

Presets and artifacts

• The layout and figure rows use Docling-official preset IDs; the three table rows are project IDs.
• src/docling_mlx/presets.py pins each mirror to an immutable commit, and each component's validation.md records that commit and the upstream source revision it was converted from.
• For an offline stage, artifacts_path is a Docling cache root. Resolution first uses <repo-id-with-slashes-replaced-by-->/<revision>/, then the legacy flat repository directory. The model spec may instead name a compatible upstream Hugging Face checkpoint. The DOCLING_MLX_*_ARTIFACT lane variables point directly to complete checkpoint directories, while the DOCLING_MLX_*_SOURCE variables name source snapshots for conversion.
• Converted weights are separate artifacts. Mirror provenance records the immutable upstream source revision; it is not a license claim. Follow the source repository's terms.

Performance

Warm median latency per item on DPBench, one fresh batch-size-one process per implementation, MLX on Metal against the official Docling stage. The layout, figure, and TableFormer outputs match the official implementations on the same inputs (identical labels, top-1 classes, and OTSL sequences); the Granite outputs differ within BF16 kernel noise. Each component's validation.md records the full comparison.

The pipeline tables report the mean per page and the timed-round total rather than the median: only pages with tables or charts run the table and Granite stages, so the median page carries none of that work.

The reduced standard pipeline (layout, table structure, and picture classification only) over all 200 DPBench PDFs, one construction-plus-inference warm-up and three timed rounds, with equivalent Heron-default layout and TableFormer settings:

The full standard pipeline with Granite Vision table structure and chart extraction over the first 50 DPBench PDFs, one construction-plus-inference warm-up and one timed round because Docling's official Granite stages run on the CPU on macOS; each side decoded 6 table crops and 14 chart crops, and markdown identity is below 1.0 because Granite differs within BF16 noise:

Machine: Apple M4 Pro, 48 GiB unified memory, macOS 26.5.2; Python 3.13.13; Docling 2.124.0, docling-ibm-models 4.0.1, MLX 0.32.2, mlx-vlm 0.6.4, Torch 2.14.0, Transformers 5.8.1; measured on 2026-09-03 with tools/compare_backends.py schema 2. The Granite pipeline table was measured on 2026-09-04 in the same environment. Regenerate the tables with tools/compare_backends.py.

Documentation

• DEVELOPMENT.md: development commands, qualification lanes, and artifact staging.
• docs/architecture.md: the boundary between engines, stages, plugins, and configure().
• Component guides and validation records: layout Heron, layout Egret, DocumentFigure, TableFormer v1, TableFormerV2, and Granite Vision.
• CONTRIBUTING.md and the commit scopes in docs/commits.md.