PDF Page Range Selection#

Docling provides two complementary mechanisms to work with specific pages of a PDF: pre-conversion filtering via page_range (limits which pages are processed by the backend) and post-conversion filtering via DoclingDocument.filter() and iterate_items(page_no=...) (operates on an already-converted document).

Pre-Conversion: page_range Parameter#

The DocumentConverter.convert() method accepts a page_range parameter — a validated Tuple[int, int] — that restricts which pages the backend processes at all.

Type and validation — PageRange is defined in docling/datamodel/settings.py as an annotated tuple with the constraint start >= 1 and end >= start. The default is (1, sys.maxsize), meaning all pages are processed unless overridden.

Data flow — page_range flows as follows 1:

convert(page_range=...) → convert_all() → DocumentLimits → _DocumentConversionInput → InputDocument.limits → backend

The DocumentLimits object is constructed inside convert_all() and attached to each InputDocument before the pipeline runs. Pages outside the range are never loaded or parsed.

Usage:

from docling.document_converter import DocumentConverter

converter = DocumentConverter()
result = converter.convert("document.pdf", page_range=(3, 7))
doc = result.document # contains only pages 3–7

Batching large PDFs — For memory-constrained workloads, process in chunks and create a fresh DocumentConverter per batch to force the C++ backend to release memory 2:

for start in range(1, total_pages, chunk_size):
    converter = DocumentConverter()
    result = converter.convert(path, page_range=(start, start + chunk_size - 1))
    del converter # forces C++ memory release

⚠️ Tables that span a batch boundary will be split across chunks.

CLI limitation — There is no --page-range flag on the local docling convert CLI command; the flag exists only for convert-remote 2.

Post-Conversion Filtering#

DoclingDocument.filter(page_nrs=...)#

DoclingDocument.filter() returns a new DoclingDocument containing only content whose provenance falls on the specified pages. It uses an internal _DocIndex to build the filtered copy 3.

filtered_doc = doc.filter(page_nrs={1, 2, 5})

Use this when you want a standalone document object for a subset of pages — e.g., to export or concatenate selectively.

DoclingDocument.iterate_items(page_no=...)#

iterate_items() supports a page_no: Optional[int] parameter for single-page scoped traversal. Internally, it converts page_no to a set and checks each item's prov list for a matching page number 4.

for item, level in doc.iterate_items(page_no=3):
    print(item)

This yields all body-layer items whose provenance includes page 3. Use this for lightweight, read-only iteration without constructing a new document.

See the Document Tree Traversal article for the full iterate_items() parameter reference.

Choosing the Right Approach#

Key Source References#

• DocumentConverter.convert() — page_range parameter entry point
• DocumentLimits / PageRange — type definition and validation
• DoclingDocument.filter() — post-conversion page filtering
• DoclingDocument.iterate_items() — page-scoped traversal