Installation Extras

The optional dependency matrix from natural_pdf.utils.optional_imports — the same data npdf doctor reports for your environment. Each extra is a pip install target; each row is one optional dependency the library probes for at runtime.

natural-pdf[ai]

Install: pip install "natural-pdf[ai]"

Dependency	Packages	What it enables	Install on its own
rapidocr	rapidocr	Default RapidOCR engine for OCR workflows.	pip install "natural-pdf[all]" or pip install rapidocr
torch	torch	PyTorch runtime used by QA/classification/layout engines.	pip install "natural-pdf[all]" or pip install torch
torchvision	torchvision	TorchVision models/utilities used by perception pipelines.	pip install "natural-pdf[all]" or pip install torchvision
huggingface_hub	huggingface_hub	Model hub utilities required by AI engines.	pip install natural-pdf or pip install huggingface_hub
mlx_vlm	mlx-vlm	MLX local VLM runtime for Apple Silicon OCR and extraction. (Platform-conditional: npdf doctor shows N/A where it does not apply.)	pip install "natural-pdf[ai]" or pip install mlx-vlm
transformers	transformers	Hugging Face transformers for QA/classification.	pip install "natural-pdf[all]" or pip install transformers
sentence_transformers	sentence-transformers	Embedding models for semantic search.	pip install "natural-pdf[all]" or pip install sentence-transformers
timm	timm	Required backbone models for layout detectors.	pip install "natural-pdf[all]" or pip install timm
doclayout_yolo	doclayout_yolo	YOLO-based layout detection models.	pip install "natural-pdf[all]" or pip install doclayout_yolo

natural-pdf[all]

Install: pip install "natural-pdf[all]"

Dependency	Packages	What it enables	Install on its own
rapidocr	rapidocr	Default RapidOCR engine for OCR workflows.	pip install "natural-pdf[all]" or pip install rapidocr
torch	torch	PyTorch runtime used by QA/classification/layout engines.	pip install "natural-pdf[all]" or pip install torch
torchvision	torchvision	TorchVision models/utilities used by perception pipelines.	pip install "natural-pdf[all]" or pip install torchvision
huggingface_hub	huggingface_hub	Model hub utilities required by AI engines.	pip install natural-pdf or pip install huggingface_hub
mlx_vlm	mlx-vlm	MLX local VLM runtime for Apple Silicon OCR and extraction. (Platform-conditional: npdf doctor shows N/A where it does not apply.)	pip install "natural-pdf[ai]" or pip install mlx-vlm
transformers	transformers	Hugging Face transformers for QA/classification.	pip install "natural-pdf[all]" or pip install transformers
sentence_transformers	sentence-transformers	Embedding models for semantic search.	pip install "natural-pdf[all]" or pip install sentence-transformers
timm	timm	Required backbone models for layout detectors.	pip install "natural-pdf[all]" or pip install timm
doclayout_yolo	doclayout_yolo	YOLO-based layout detection models.	pip install "natural-pdf[all]" or pip install doclayout_yolo
pikepdf	pikepdf	Required for creating searchable PDFs.	pip install "natural-pdf[export]"
img2pdf	img2pdf	Image to PDF conversion helper used by deskew/save routines.	pip install "natural-pdf[export]"
openpyxl	openpyxl	Spreadsheet writer used for Excel exports.	pip install "natural-pdf[export]"
jupytext	jupytext	Notebook/text conversion support for export workflows.	pip install "natural-pdf[export]"
nbformat	nbformat	Notebook format support for export workflows.	pip install "natural-pdf[export]"
spellchecker	pyspellchecker	Dictionary lookups for the to_llm garble-rate diagnostic.	pip install "natural-pdf[all]" or pip install pyspellchecker
langdetect	langdetect	Language detection for the to_llm garble-rate diagnostic.	pip install "natural-pdf[all]" or pip install langdetect

natural-pdf[export]

Install: pip install "natural-pdf[export]"

Dependency	Packages	What it enables	Install on its own
pikepdf	pikepdf	Required for creating searchable PDFs.	pip install "natural-pdf[export]"
img2pdf	img2pdf	Image to PDF conversion helper used by deskew/save routines.	pip install "natural-pdf[export]"
openpyxl	openpyxl	Spreadsheet writer used for Excel exports.	pip install "natural-pdf[export]"
jupytext	jupytext	Notebook/text conversion support for export workflows.	pip install "natural-pdf[export]"
nbformat	nbformat	Notebook format support for export workflows.	pip install "natural-pdf[export]"

natural-pdf[paddle]

Install: pip install "natural-pdf[paddle]"

Dependency	Packages	What it enables	Install on its own
chardet	chardet	Character encoding detection dependency used by Paddle OCR tooling.	pip install "natural-pdf[paddle]" or pip install chardet
paddlepaddle	paddlepaddle	PaddlePaddle runtime for PaddleOCR.	pip install "natural-pdf[paddle]" or pip install paddlepaddle
paddleocr	paddleocr	PaddleOCR and PaddleOCR-VL engine stack.	pip install "natural-pdf[paddle]" or pip install paddleocr
paddlex	paddlex	PaddleX OCR pipeline dependency.	pip install "natural-pdf[paddle]" or pip install paddlex[ocr]
numpy	numpy	Numeric runtime dependency; the Paddle extra pins this below 2.0.	pip install "natural-pdf[paddle]" or pip install 'numpy<2.0'

natural-pdf[quality]

Install: pip install "natural-pdf[quality]"

Dependency	Packages	What it enables	Install on its own
spellchecker	pyspellchecker	Dictionary lookups for the to_llm garble-rate diagnostic.	pip install "natural-pdf[all]" or pip install pyspellchecker
langdetect	langdetect	Language detection for the to_llm garble-rate diagnostic.	pip install "natural-pdf[all]" or pip install langdetect

Not in any extra

These optional dependencies are opt-in: install them individually.

Dependency	Packages	What it enables	Install on its own
doctr	python-doctr	Opt-in Doctr OCR engine.	pip install python-doctr
easyocr	easyocr	Opt-in EasyOCR engine for OCR workflows.	pip install easyocr
surya	surya-ocr	Opt-in Surya OCR engine.	pip install surya-ocr