crewAIInc/crewAI · error · ImportError

python-docx is required for DOCX loading. Install with: 'uv

Error message

python-docx is required for DOCX loading. Install with: 'uv pip install python-docx' or pip install crewai-tools[rag]

What it means

Raised by DOCXLoader.load() when the optional python-docx dependency is not installed. The import of docx.Document happens lazily inside load() so that crewai-tools can be installed without DOCX support; on ImportError the loader re-raises with install instructions and chains the original error.

Source

Thrown at lib/crewai-tools/src/crewai_tools/rag/loaders/docx_loader.py:15

import os
import tempfile
from typing import Any

from crewai_tools.rag.base_loader import BaseLoader, LoaderResult
from crewai_tools.rag.source_content import SourceContent
from crewai_tools.security.safe_requests import safe_get


class DOCXLoader(BaseLoader):
    def load(self, source_content: SourceContent, **kwargs: Any) -> LoaderResult:  # type: ignore[override]
        try:
            from docx import Document as DocxDocument
        except ImportError as e:
            raise ImportError(
                "python-docx is required for DOCX loading. Install with: 'uv pip install python-docx' or pip install crewai-tools[rag]"
            ) from e

        source_ref = source_content.source_ref

        if source_content.is_url():
            temp_file = self._download_from_url(source_ref, kwargs)
            try:
                return self._load_from_file(temp_file, source_ref, DocxDocument)
            finally:
                os.unlink(temp_file)
        elif source_content.path_exists():
            return self._load_from_file(source_ref, source_ref, DocxDocument)
        else:
            raise ValueError(
                f"Source must be a valid file path or URL, got: {source_content.source}"
            )

View on GitHub (pinned to 754d7323be)

Solutions

Install the dependency: `pip install crewai-tools[rag]` or `pip install python-docx` (note: the import name is docx but the package name is python-docx).
If using uv, add it to the project: `uv add python-docx` or reinstall with the rag extra `uv pip install 'crewai-tools[rag]'`.
Rebuild/refresh the environment (uv sync / pip install -r requirements.txt) so the lockfile includes the extra.
Guard optional-format features behind an availability check (importlib.util.find_spec('docx')) and disable DOCX ingestion with a clear message when absent.

Example fix

# before
loader = DOCXLoader()
result = loader.load(SourceContent('spec.docx'))  # ImportError

# after
# terminal: pip install 'crewai-tools[rag]'
import importlib.util
if importlib.util.find_spec('docx') is None:
    raise RuntimeError('DOCX ingestion disabled: run pip install crewai-tools[rag]')
result = DOCXLoader().load(SourceContent('spec.docx'))

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try:\n    result = DOCXLoader().load(source)\nexcept ImportError as e:\n    raise RuntimeError('DOCX ingestion unavailable in this image') from e

Prevention

Install crewai-tools[rag] in every environment that ingests documents.
Add a startup capability check listing required optional deps.
Bake extras into Docker images rather than installing at runtime.

When it happens

Trigger: Calling DOCXLoader().load(...) in an environment where crewai-tools was installed without the [rag] extra and python-docx was never installed; a fresh virtualenv after a minimal `pip install crewai-tools`; dependency pruning by a lockfile or Docker layer that dropped the optional package.

Common situations: Installing crewai-tools without extras in CI or slim Docker images; uv/pip environments where the extra was added to pyproject but never synced; upgrading crewai-tools and the new version made python-docx optional; sharing an environment where a teammate installed the minimal package set.

Related errors

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