Install & Compatibility
Where this runs
tested against v7.16.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
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 14.4s · import 2.308s · 255MB
256MB installed
● package 256MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DoclingPdfParser
✓ from docling_parse.pdf_parser import DoclingPdfParser
Primary class for PDF parsing.
PdfDocument
✓ from docling_parse.pdf_parser import PdfDocument
Represents the parsed PDF document structure.
TextCellUnit
✓ from docling_core.types.doc.page import TextCellUnit
Enum for specifying text unit granularity (char, word, line).
pdf_parser_v2
✓ from docling_parse.pdf_parser import DoclingPdfParser
✗ from docling_parse.docling_parse import pdf_parser_v2
Older versions of `docling-parse` or its parent `docling` might have used `pdf_parser_v2`. The current approach is to import `DoclingPdfParser` from `docling_parse.pdf_parser` directly.
This quickstart demonstrates how to initialize the `DoclingPdfParser`, load a PDF document, and iterate through its pages to extract text at the word level, including bounding box coordinates. It also shows the import paths for necessary components. For a runnable example, ensure you replace `"path/to/your/document.pdf"` with a valid PDF file path. The example also briefly mentions rendering pages as images.
import os
from docling_core.types.doc.page import TextCellUnit
from docling_parse.pdf_parser import DoclingPdfParser, PdfDocument
# Create a dummy PDF file for demonstration
# In a real scenario, you'd have an actual PDF file path
# This simple quickstart cannot create a real PDF to parse,
# so we'll use a placeholder and note the expected input.
# Replace "path/to/your/document.pdf" with an actual PDF file path
pdf_file_path = "path/to/your/document.pdf"
# Ensure the PDF file exists for a real-world execution
# For this example, we'll just demonstrate the API calls.
if not os.path.exists(pdf_file_path):
print(f"Warning: PDF file not found at '{pdf_file_path}'. This example requires a valid PDF.")
print("Please replace 'path/to/your/document.pdf' with an actual path to a PDF.")
# Exit or mock for testing purposes if no real PDF is available
# For a runnable example, a simple PDF is required.
# Skipping parsing for non-existent file.
else:
parser = DoclingPdfParser()
# Load the PDF document
pdf_doc: PdfDocument = parser.load(path_or_stream=pdf_file_path)
# Iterate over pages and extract words
print(f"Processing PDF: {pdf_file_path}")
for page_no, pred_page in pdf_doc.iterate_pages():
print(f"\n--- Page {page_no + 1} ---")
# Iterate over the word-cells on the page
for word in pred_page.iterate_cells(unit_type=TextCellUnit.WORD):
print(f"Rect: {word.rect}, Text: '{word.text}'")
# Optionally, render the page as an image (requires Pillow)
# img = pred_page.render_as_image(cell_unit=TextCellUnit.CHAR)
# img.show() # This would open the image if Pillow is installed
Debug
Known issues
breakingWith the introduction of `docling-parse` v5, previous parsing backends (especially those integrated directly into the `docling` parent project) were deprecated. Users migrating from older `docling` versions (pre-2.73.1) relying on internal parser implementations may need to update their code to use the `docling-parse` v5 API explicitly.fixEnsure you are importing `DoclingPdfParser` and `PdfDocument` from `docling_parse.pdf_parser` and `TextCellUnit` from `docling_core.types.doc.page`. Review official documentation for the latest API usage if coming from a significantly older setup.
affects: <5.0.0 (indirectly via docling)
gotchaThe `docling-parse` library requires Python 3.10 or higher. Installations on older Python versions will fail or result in unexpected behavior.fixUpgrade your Python environment to version 3.10 or newer.
affects: <5.0.0
gotchaParsing large PDF documents 'in one go' using `parser.parse_pdf_from_key()` (from older API) or similar memory-intensive methods can consume significant memory. The recommended approach for memory optimization is to process PDFs page by page.fixUtilize `pdf_doc.iterate_pages()` and process each page individually to minimize memory footprint, especially for large documents. If using `DoclingThreadedPdfParser`, configure `max_concurrent_results` appropriately.
affects: All versions
gotchaMalformed or broken PDF documents can lead to parsing errors or infinite loops. Recent fixes (v5.3.4, v5.6.2) addressed issues like 'Robustify parse of broken pdfs' and 'Prevent infinite loop in TOC extraction with circular PDF refererences'. [cite: 23, 246 (from prompt)]fixEnsure PDFs are well-formed where possible. Keep `docling-parse` updated to the latest version to benefit from robustness improvements. Implement robust error handling around PDF loading and parsing operations.
affects: <5.6.2
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'docling_parse.pdf_parsers'; 'docling_parse' is not a package
This error typically occurs due to a version incompatibility or a module renaming issue between the `docling` library and its backend `docling-parse`. Specifically, `docling` might be trying to import `docling_parse.pdf_parsers` (or `pdf_parser`), but the installed `docling-parse` version provides a different module name or structure.
fixEnsure both `docling` and `docling-parse` are updated to compatible versions, often by upgrading both packages: `pip install --upgrade docling docling-parse`. Also, verify there isn't a local file or directory shadowing the `docling_parse` package in your environment.
FileNotFoundError: [Errno 2] No such file or directory: '<string_content>'
When using `docling.document_converter.DocumentConverter`, providing a string that contains the actual document content (instead of a file path or URL) causes the converter to incorrectly interpret the content string as a non-existent file path, leading to this error.
fixTo process in-memory document content, wrap the content (as bytes) in an `io.BytesIO` object and pass it as a `DocumentStream` to the converter.
```python
from io import BytesIO
from docling.document_converter import DocumentConverter
from docling.datamodel.document import DocumentStream # Assuming this path
# Example: actual PDF content as bytes
pdf_content_bytes = b'%PDF-1.4...\n%%EOF'
converter = DocumentConverter()
stream = DocumentStream(BytesIO(pdf_content_bytes))
doc = converter.convert(stream).document
# Process doc...
```
ERROR: Failed building wheel for docling-parse
`docling-parse` contains C++ extensions and requires a C++ compiler and specific system dependencies to build successfully. This error usually indicates that the necessary build tools (like `gcc`/`clang`), Python development headers, or compatible pre-built wheels are not available for your operating system or Python version.
fixEnsure you have a C++ compiler installed (e.g., Xcode Command Line Tools on macOS, Visual C++ build tools on Windows, `build-essential` package on Debian/Ubuntu). For Linux, also install Python development headers (e.g., `sudo apt-get install python3-dev`). On macOS, specific `numpy` version pinning might be required due to PyTorch dependencies: `pip install "numpy<2.0.0"` before installing `docling-parse`.
AttributeError: 'NoneType' object has no attribute 'text'
This error occurs during the parsing of certain `.pptx` (PowerPoint) documents within the `docling` library's `MsPowerpointDocumentBackend`. It signifies that the parser attempted to access a text frame or a similar element (e.g., `notes_text_frame`) that was expected but found to be `None` for a particular slide or content, possibly due to a malformed or unusual `.pptx` structure.
fixThis is often an internal bug in `docling`'s handling of specific `.pptx` structures. Update `docling` and `docling-parse` to their latest versions, as such issues are frequently addressed in patch releases: `pip install --upgrade docling docling-parse`. If the issue persists with a specific document, consider simplifying the `.pptx` file or reporting the issue to the `docling` project on GitHub.
Upgrade
Version history
7.16.0latest on PyPI · released Aug 25, 2026
Audit
Dependencies
docling-corerequiredProvides core data types and structures for Docling.
pillowrequiredRequired for image rendering capabilities.
pydanticrequiredUsed for data validation and settings management.
tabulaterequiredUsed for table formatting in some outputs.