{"record":{"id":"ac9d2a85ac394d9d","repo":"crewAIInc/crewAI","slug":"python-docx-is-required-for-docx-loading-install","errorCode":null,"errorMessage":"python-docx is required for DOCX loading. Install with: 'uv pip install python-docx' or pip install crewai-tools[rag]","messagePattern":"python-docx is required for DOCX loading\\. Install with: 'uv pip install python-docx' or pip install crewai-tools\\[rag\\]","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"lib/crewai-tools/src/crewai_tools/rag/loaders/docx_loader.py","lineNumber":15,"sourceCode":"import os\nimport tempfile\nfrom typing import Any\n\nfrom crewai_tools.rag.base_loader import BaseLoader, LoaderResult\nfrom crewai_tools.rag.source_content import SourceContent\nfrom crewai_tools.security.safe_requests import safe_get\n\n\nclass DOCXLoader(BaseLoader):\n    def load(self, source_content: SourceContent, **kwargs: Any) -> LoaderResult:  # type: ignore[override]\n        try:\n            from docx import Document as DocxDocument\n        except ImportError as e:\n            raise ImportError(\n                \"python-docx is required for DOCX loading. Install with: 'uv pip install python-docx' or pip install crewai-tools[rag]\"\n            ) from e\n\n        source_ref = source_content.source_ref\n\n        if source_content.is_url():\n            temp_file = self._download_from_url(source_ref, kwargs)\n            try:\n                return self._load_from_file(temp_file, source_ref, DocxDocument)\n            finally:\n                os.unlink(temp_file)\n        elif source_content.path_exists():\n            return self._load_from_file(source_ref, source_ref, DocxDocument)\n        else:\n            raise ValueError(\n                f\"Source must be a valid file path or URL, got: {source_content.source}\"\n            )\n","sourceCodeStart":1,"sourceCodeEnd":33,"githubUrl":"https://github.com/crewAIInc/crewAI/blob/754d7323beb2fd042e33444a115ea2d5a47193f0/lib/crewai-tools/src/crewai_tools/rag/loaders/docx_loader.py#L1-L33","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nloader = DOCXLoader()\nresult = loader.load(SourceContent('spec.docx'))  # ImportError\n\n# after\n# terminal: pip install 'crewai-tools[rag]'\nimport importlib.util\nif importlib.util.find_spec('docx') is None:\n    raise RuntimeError('DOCX ingestion disabled: run pip install crewai-tools[rag]')\nresult = DOCXLoader().load(SourceContent('spec.docx'))","handlingStrategy":"validation","validationCode":"import importlib.util\\n\\ndef docx_supported() -> bool:\\n    return importlib.util.find_spec('docx') is not None","typeGuard":null,"tryCatchPattern":"try:\\n    result = DOCXLoader().load(source)\\nexcept ImportError as e:\\n    raise RuntimeError('DOCX ingestion unavailable in this image') from e","preventionTips":["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."],"tags":["dependencies","import","loader","docx"],"backgroundTag":null,"analyzedSha":"754d7323beb2fd042e33444a115ea2d5a47193f0","analyzedAt":"2026-08-15T04:06:56.746Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}