{"record":{"id":"f82228e9984b79e4","repo":"unclecode/crawl4ai","slug":"pypdf-is-required-for-pdf-processing-install-with","errorCode":null,"errorMessage":"pypdf is required for PDF processing. Install with 'pip install crawl4ai[pdf]'","messagePattern":"pypdf is required for PDF processing\\. Install with 'pip install crawl4ai\\[pdf\\]'","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"crawl4ai/processors/pdf/processor.py","lineNumber":64,"sourceCode":"class PDFProcessResult:\n    metadata: PDFMetadata\n    pages: List[PDFPage]\n    processing_time: float = 0.0\n    version: str = \"1.0\"\n\nclass PDFProcessorStrategy(ABC):\n    @abstractmethod\n    def process(self, pdf_path: Path) -> PDFProcessResult:\n        pass\n\nclass NaivePDFProcessorStrategy(PDFProcessorStrategy):\n    def __init__(self, image_dpi: int = 144, image_quality: int = 85, extract_images: bool = True, \n                 save_images_locally: bool = False, image_save_dir: Optional[Path] = None, batch_size: int = 4):\n        # Import check at initialization time\n        try:\n            import pypdf\n        except ImportError:\n            raise ImportError(\"pypdf is required for PDF processing. Install with 'pip install crawl4ai[pdf]'\")\n            \n        self.image_dpi = image_dpi\n        self.image_quality = image_quality\n        self.current_page_number = 0\n        self.extract_images = extract_images\n        self.save_images_locally = save_images_locally\n        self.image_save_dir = image_save_dir\n        self.batch_size = batch_size\n        self._temp_dir = None\n\n    def process(self, pdf_path: Path) -> PDFProcessResult:\n        # Import inside method to allow dependency to be optional\n        try:\n            from pypdf import PdfReader\n        except ImportError:\n            raise ImportError(\"pypdf is required for PDF processing. Install with 'pip install crawl4ai[pdf]'\")\n            \n        start_time = time()","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/unclecode/crawl4ai/blob/7e801521428ee12509994d39151006f64055ebe3/crawl4ai/processors/pdf/processor.py#L46-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nstrategy = NaivePDFProcessorStrategy()  # ImportError: pypdf is required ...\n\n# after (shell)\n# pip install 'crawl4ai[pdf]'\nstrategy = NaivePDFProcessorStrategy()","handlingStrategy":"validation","validationCode":"def pdf_extra_available() -> bool:\n    try:\n        import pypdf  # noqa: F401\n        return True\n    except ImportError:\n        return False\n\nassert pdf_extra_available(), \"pip install 'crawl4ai[pdf]' before enabling PDF crawling\"","typeGuard":null,"tryCatchPattern":"try:\n    strategy = NaivePDFProcessorStrategy()\nexcept ImportError as e:\n    if 'crawl4ai[pdf]' in str(e):\n        raise SystemExit(\"Missing PDF extra. Run: pip install 'crawl4ai[pdf]'\") from e","preventionTips":["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."],"tags":["pdf","dependency","import-error","installation"],"backgroundTag":null,"analyzedSha":"7e801521428ee12509994d39151006f64055ebe3","analyzedAt":"2026-08-14T20:46:20.673Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}