unclecode/crawl4ai · error · ImportError

pypdf is required for PDF processing. Install with 'pip inst

Error message

pypdf is required for PDF processing. Install with 'pip install crawl4ai[pdf]'

What it means

ImportError raised in NaivePDFProcessorStrategy.__init__ when the optional pypdf dependency is not installed. crawl4ai keeps PDF support extras-optional, so the constructor eagerly validates availability and points to the 'crawl4ai[pdf]' extra rather than failing later mid-crawl.

Source

Thrown at crawl4ai/processors/pdf/processor.py:64

class PDFProcessResult:
    metadata: PDFMetadata
    pages: List[PDFPage]
    processing_time: float = 0.0
    version: str = "1.0"

class PDFProcessorStrategy(ABC):
    @abstractmethod
    def process(self, pdf_path: Path) -> PDFProcessResult:
        pass

class NaivePDFProcessorStrategy(PDFProcessorStrategy):
    def __init__(self, image_dpi: int = 144, image_quality: int = 85, extract_images: bool = True, 
                 save_images_locally: bool = False, image_save_dir: Optional[Path] = None, batch_size: int = 4):
        # Import check at initialization time
        try:
            import pypdf
        except ImportError:
            raise ImportError("pypdf is required for PDF processing. Install with 'pip install crawl4ai[pdf]'")
            
        self.image_dpi = image_dpi
        self.image_quality = image_quality
        self.current_page_number = 0
        self.extract_images = extract_images
        self.save_images_locally = save_images_locally
        self.image_save_dir = image_save_dir
        self.batch_size = batch_size
        self._temp_dir = None

    def process(self, pdf_path: Path) -> PDFProcessResult:
        # Import inside method to allow dependency to be optional
        try:
            from pypdf import PdfReader
        except ImportError:
            raise ImportError("pypdf is required for PDF processing. Install with 'pip install crawl4ai[pdf]'")
            
        start_time = time()

View on GitHub (pinned to 7e80152142)

Solutions

Install the PDF extra: pip install 'crawl4ai[pdf]'.
Or install pypdf directly: pip install pypdf.
Verify the right interpreter: python -c 'import pypdf; print(pypdf.__version__)' in the same venv that runs crawl4ai.
In containerized deployments, rebuild the image with the extra included in requirements.

Example fix

# before
strategy = NaivePDFProcessorStrategy()  # ImportError: pypdf is required ...

# after (shell)
# pip install 'crawl4ai[pdf]'
strategy = NaivePDFProcessorStrategy()

Defensive patterns

Strategy: validation

Validate before calling

def pdf_extra_available() -> bool:
    try:
        import pypdf  # noqa: F401
        return True
    except ImportError:
        return False

assert pdf_extra_available(), "pip install 'crawl4ai[pdf]' before enabling PDF crawling"

Try / catch

try:
    strategy = NaivePDFProcessorStrategy()
except ImportError as e:
    if 'crawl4ai[pdf]' in str(e):
        raise SystemExit("Missing PDF extra. Run: pip install 'crawl4ai[pdf]'") from e

Prevention

Pin 'crawl4ai[pdf]' (not bare crawl4ai) in requirements when crawling PDFs.
Add a startup dependency check that imports pypdf in the runtime interpreter.
Verify venv/container parity: the interpreter running crawl4ai must be the one with pypdf.

When it happens

Trigger: Instantiating NaivePDFProcessorStrategy (directly or via the default PDF processing pipeline used when crawling PDFs) in an environment where `import pypdf` raises ImportError — i.e. pypdf was never installed or was uninstalled.

Common situations: Installing crawl4ai without the [pdf] extra, using a minimal Docker image that strips optional deps, a venv mismatch where crawl4ai runs in an interpreter without pypdf, or a broken pypdf install.

Related errors

AI-assisted analysis of unclecode/crawl4ai@7e80152142 (2026-08-14). Data as JSON: /api/errors/f82228e9984b79e4. Report an issue: GitHub.