crewAIInc/crewAI · error · ImportError

PDF support requires pymupdf. Install with: uv add pymupdf

Error message

PDF support requires pymupdf. Install with: uv add pymupdf

What it means

Raised by PDFLoader.load() when pymupdf (fitz) is not installed. The import happens lazily inside load(), so environments without optional PDF support fail only when a PDF is actually loaded; the error tells you to add pymupdf and chains the original ImportError.

Source

Thrown at lib/crewai-tools/src/crewai_tools/rag/loaders/pdf_loader.py:86

    def load(self, source: SourceContent, **kwargs: Any) -> LoaderResult:  # type: ignore[override]
        """Load and extract text from a PDF file or URL.

        Args:
            source: The source content containing the PDF file path or URL.

        Returns:
            LoaderResult with extracted text content.

        Raises:
            FileNotFoundError: If the PDF file doesn't exist.
            ImportError: If required PDF libraries aren't installed.
            ValueError: If the PDF cannot be read or downloaded.
        """
        try:
            import pymupdf  # type: ignore[import-untyped]
        except ImportError as e:
            raise ImportError(
                "PDF support requires pymupdf. Install with: uv add pymupdf"
            ) from e

        file_path = source.source
        is_url = self._is_url(file_path)

        if is_url:
            source_name = Path(urlparse(file_path).path).name or "downloaded.pdf"
        else:
            source_name = Path(file_path).name

        text_content: list[str] = []
        metadata: dict[str, Any] = {
            "source": file_path,
            "file_name": source_name,
            "file_type": "pdf",
        }

View on GitHub (pinned to 754d7323be)

Solutions

Install the dependency: `uv add pymupdf` or `pip install pymupdf` (or `pip install crewai-tools[rag]`).
Refresh the whole environment from the lockfile after adding the extra.
Guard optional ingestion paths behind importlib.util.find_spec('pymupdf') and skip PDF sources with a clear warning when absent.

Example fix

# before
result = PDFLoader().load(SourceContent('manual.pdf'))  # ImportError

# after
# terminal: uv add pymupdf
import importlib.util
if importlib.util.find_spec('pymupdf') is None:
    raise RuntimeError('PDF ingestion disabled: run `uv add pymupdf`')
result = PDFLoader().load(SourceContent('manual.pdf'))

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util\n\ndef pdf_supported() -> bool:\n    return importlib.util.find_spec('pymupdf') is not None

Try / catch

try:\n    result = PDFLoader().load(source)\nexcept ImportError as e:\n    raise RuntimeError('PDF ingestion unavailable: uv add pymupdf') from e

Prevention

Include pymupdf in every image/env that touches PDFs.
Startup-check optional deps once, not per document.
Keep a capability manifest of optional formats your deployment supports.

When it happens

Trigger: Calling PDFLoader().load(...) where crewai-tools was installed without the rag extra containing pymupdf; fresh minimal virtualenvs; dependency pruning in slim containers or after lockfile updates.

Common situations: Minimal `pip install crewai-tools` installs in CI; uv projects where the extra was never added; teams assuming PDF support is bundled in core; Docker images built from scratch layers that dropped optional deps.

Related errors

AI-assisted analysis of crewAIInc/crewAI@754d7323be (2026-08-15). Data as JSON: /api/errors/83f455b542fa27fd. Report an issue: GitHub.