ImportError / ModuleNotFoundError
unstructured.partition.pdf.ImportError: Missing required dependencies for PDF processing
Stack trace
ImportError: pdf2image is required to process PDF files. Install it with: pip install pdf2image
Or for full PDF support:
pip install unstructured[pdf]
---
Traceback (most recent call last):
File "main.py", line 12, in <module>
from unstructured.partition.pdf import partition_pdf
File "/usr/local/lib/python3.9/site-packages/unstructured/partition/pdf.py", line 5, in <module>
import pdf2image
ModuleNotFoundError: No module named 'pdf2image' Why it happens
The unstructured package makes PDF processing dependencies optional to keep the base package lightweight. When you call partition_pdf(), the library imports pdf2image and pytesseract at runtime: if these packages aren't installed, Python raises ModuleNotFoundError immediately. Additionally, pytesseract requires a system-level Tesseract OCR binary, which must be installed separately on your OS (not available via pip).
Detection
Before calling partition_pdf() in production, verify dependencies with: python -c "import pdf2image; import pytesseract" and check that tesseract binary exists on your system with: which tesseract (Linux/macOS) or where tesseract (Windows). Add this validation to your startup or CI/CD health checks.
Causes & fixes
pdf2image Python package not installed
Run: pip install pdf2image: or better, pip install 'unstructured[pdf]' which installs all PDF-related dependencies at once
pytesseract Python package missing (needed for OCR on scanned PDFs)
Run: pip install pytesseract: also install system Tesseract binary: brew install tesseract (macOS), apt-get install tesseract-ocr (Ubuntu), or download installer (Windows)
Pillow (PIL) not installed, required by pdf2image
Run: pip install Pillow: usually installed automatically as pdf2image dependency, but if missing: pip install --upgrade Pillow
Tesseract binary installed but not in system PATH
On Windows: pytesseract.pytesseract.pytesseract_cmd = 'C:\\Program Files\\Tesseract-OCR\\tesseract.exe' before importing pytesseract. On Linux/macOS: ensure /usr/bin/tesseract or /usr/local/bin/tesseract exists
Code: broken vs fixed
import os
from unstructured.partition.pdf import partition_pdf # ❌ ImportError: No module named 'pdf2image'
pdf_path = '/path/to/document.pdf'
# This line fails immediately because pdf2image is not installed
elements = partition_pdf(pdf_path)
for elem in elements:
print(elem.text)import os
import sys
from unstructured.partition.pdf import partition_pdf
# ✅ FIXED: Dependencies installed via: pip install 'unstructured[pdf]'
# On macOS: brew install tesseract
# On Ubuntu: apt-get install tesseract-ocr
# On Windows: Download and run Tesseract installer, then set path below if needed
# Optional: For Windows users, uncomment and set correct Tesseract path
# import pytesseract
# pytesseract.pytesseract.pytesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe'
pdf_path = os.environ.get('PDF_PATH', '/path/to/document.pdf')
try:
elements = partition_pdf(pdf_path)
print(f"✓ Successfully parsed {len(elements)} elements")
for elem in elements:
print(f"[{elem.type}] {elem.text[:100]}")
except ModuleNotFoundError as e:
print(f"❌ Missing dependency: {e}")
print("Run: pip install 'unstructured[pdf]'")
sys.exit(1)Workaround
If you cannot install system Tesseract (e.g., restricted environment), use text-extraction-only mode: set strategy='fast' in partition_pdf() which skips OCR and relies on embedded PDF text only. For scanned PDFs without embedded text, convert PDF pages to images with pdf2image and send them to gpt-4o vision for OCR instead: from pdf2image import convert_from_path; images = convert_from_path(pdf_path); then pass each image to OpenAI's vision endpoint.
Prevention
In your project setup, create a requirements-pdf.txt file with: unstructured[pdf]>=0.10.0 and document system dependencies in a Dockerfile or setup script: RUN apt-get install -y tesseract-ocr poppler-utils. Add a startup health check: python -c 'from unstructured.partition.pdf import partition_pdf' to verify dependencies before processing. For cloud deployments (Lambda, Cloud Run), use container images that pre-install Tesseract, or switch to a hosted document API like AWS Textract which handles OCR server-side.