Install & Compatibility
Where this runs
tested against v2.123.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ timeout
py 3.11
✕ timeout
✕ timeout
py 3.12
✕ build_error
✕ timeout
py 3.13
✕ build_error
✓ 93s
py 3.9
✕ build_error
✕ timeout
5632MB installed
● package 5632MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DocumentConverter
✓ from docling.document_converter import DocumentConverter
DoclingDocument
✓ from docling.document import DoclingDocument
The DoclingDocument is typically accessed via the result object of a conversion.
This quickstart demonstrates how to convert a document (from a URL in this example) into a structured DoclingDocument and then export its content to Markdown format. Docling automatically detects the document type and provides a `result` object containing the `DoclingDocument`, conversion `status`, and input details.
import os
from docling.document_converter import DocumentConverter
# Example: Convert a document from a URL and export to Markdown
# Docling supports local file paths, URLs, or file-like objects.
source_url = os.environ.get('DOCLING_EXAMPLE_URL', 'https://arxiv.org/pdf/2408.09869')
# Initialize the DocumentConverter
converter = DocumentConverter()
try:
# Convert the document
result = converter.convert(source_url)
# Check conversion status
if result.status == 'SUCCESS':
# Access the structured document and export it to Markdown
markdown_output = result.document.export_to_markdown()
print(markdown_output[:500]) # Print first 500 characters
print("\n... (truncated output)")
else:
print(f"Document conversion failed or was partial: {result.status}")
# You can inspect result.input for details about the source
except Exception as e:
print(f"An error occurred during conversion: {e}")
docling --version
Debug
Known issues
breakingPython 3.9 support was dropped in Docling version 2.70.0. Users on Python 3.9 or older must upgrade their Python environment.fixUpgrade Python to version 3.10 or higher. For example, use Python 3.10, 3.11, or 3.12.
affects: >=2.70.0
gotchaThe `convert()` method returns a `result` object, not the `DoclingDocument` directly. The document, its status, and input information are encapsulated within this `result` object.fixAccess the document via `result.document`, the status via `result.status`, and input details via `result.input`.
affects: All versions
gotchaIntegrating Docling into multi-threaded applications may require careful resource management to avoid thread-safety issues, especially with backend resources like pypdfium, which had previous fixes related to thread-unsafe closures.fixReview Docling's documentation on advanced usage, resource management, and potential configurations for multi-threaded environments. Ensure proper handling of `DocumentConverter` instances and their underlying resources.
affects: All versions (specific fix in v2.81.0, but general principle applies)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'docling.document_converter'; 'docling' is not a package
This error typically occurs when the Python interpreter cannot find the 'docling' package or its submodules, often due to running a script from a directory named 'docling', having a conflicting 'docling.py' file, or a corrupted/incomplete installation of 'docling' or its sub-dependencies like 'docling-parse'.
fixRename any local 'docling.py' files or directories named 'docling' in your project. Ensure 'docling' and 'docling-core' (and 'docling-parse' if applicable) are correctly installed and up-to-date in your environment using `pip install --upgrade docling docling-core docling-parse`.
ImportError: libGL.so.1: cannot open shared object file: No such file or directory
This error originates from conflicting OpenCV distributions (e.g., 'opencv-python' and 'opencv-python-headless' installed together) in Docling's third-party dependencies, or the absence of the 'libGL' system dependency, especially in headless environments like Docker containers or remote VMs that lack the OpenGL UI framework.
fixEither ensure only one OpenCV package is installed (prefer `pip uninstall opencv-python && pip install opencv-python-headless` for server environments) or install the `libGL` system dependency (e.g., `sudo apt-get install libgl1-mesa-glx` on Debian/Ubuntu, `sudo yum install mesa-libGL` on CentOS/RHEL).
authentication failed 401
Docling's API or integrated services (such as Hugging Face models) require an API key for authentication, which is either missing, incorrect, or not provided in the expected format (e.g., `X-API-Key` header for Docling API, or a Hugging Face token for model downloads).
fixFor Docling API calls, provide the correct API key in the `X-API-Key` header. For Hugging Face models, log in via the Hugging Face CLI (`huggingface-cli login`) or ensure the `HF_TOKEN` environment variable is set with your Hugging Face access token.
AttributeError: 'transformers.tokenization_utils_base.PreTrainedTokenizerBase' object has no attribute 'model_type' (or similar during formula enrichment)
This `AttributeError` occurs due to a bug in the `transformers` library (specifically with versions around 4.57.2) when it loads a model configuration as a plain dictionary instead of a proper object. This happens when `AutoProcessor.from_pretrained()` is called with a local `Path` object for models like 'CodeFormula'.
fixInstead of using a local path, call `AutoProcessor.from_pretrained()` with the model's Hugging Face name (e.g., `'docling-project/CodeFormulaV2'`). The `transformers` library will then correctly load the configuration and use the cached model if available.
ERROR: Failed building wheel for docling-parse
This installation error typically occurs when 'docling-parse' cannot build its wheel, often due to issues with build tools (like `wheel` or `cython`), C compiler environments, or Python/NumPy version incompatibilities on specific operating systems, such as macOS x86_64.
fixEnsure `wheel` and `cython` are updated (`pip install --upgrade wheel cython`). For macOS x86_64, specifically install a compatible NumPy version for Docling, for example: `pip install "docling[mac_intel]" "numpy<2.0.0"`, and ensure your Python version is 3.12 or lower if using PyTorch 2.2.2.
Upgrade
Version history
2.123.0latest on PyPI · released Aug 26, 2026
Audit
Dependencies
No dependency data recorded yet.