crewAIInc/crewAI · error · ImportError

Reading DOCX URLs requires python-docx. Install with: uv add

Error message

Reading DOCX URLs requires python-docx. Install with: uv add python-docx

What it means

UrlReadTool's DOCX extraction lazily imports 'python-docx' (from docx import Document) inside _extract_docx. When the tool fetches a Word document URL and python-docx is absent, ImportError is raised with the install command.

Source

Thrown at lib/crewai-tools/src/crewai_tools/tools/url_read_tool/url_read_tool.py:274

            pages = [
                f"Page {number}:\n{text}"
                for number, page in enumerate(document, 1)
                if (text := page.get_text().strip())
            ]
        finally:
            document.close()

        if not pages:
            return "[PDF with no extractable text]"
        return "\n\n".join(pages)

    @staticmethod
    def _extract_docx(body: bytes) -> str:
        """Extract paragraph text from DOCX bytes."""
        try:
            from docx import Document
        except ImportError as e:
            raise ImportError(
                "Reading DOCX URLs requires python-docx. Install with: "
                "uv add python-docx"
            ) from e

        document = Document(BytesIO(body))
        return "\n".join(
            paragraph.text
            for paragraph in document.paragraphs
            if paragraph.text.strip()
        )

    def _extract_html(self, body: bytes, content_type: str) -> str:
        """Strip HTML bytes down to visible text."""
        try:
            from bs4 import BeautifulSoup
        except ImportError as e:
            raise ImportError(
                "Reading HTML URLs requires beautifulsoup4. Install with: "

View on GitHub (pinned to 754d7323be)

Solutions

Install the dependency: uv add python-docx (or pip install python-docx).
Include python-docx in project dependencies if DOCX URLs are in scope.
Pre-check the URL extension/content type and skip unsupported types when the parser lib is missing.

Example fix

# before
tool.run('https://example.com/spec.docx')  # ImportError: requires python-docx

# after
# shell: uv add python-docx
tool.run('https://example.com/spec.docx')

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if not importlib.util.find_spec('docx'):
    raise SystemExit('UrlReadTool needs python-docx for DOCX URLs: uv add python-docx')

Try / catch

try:
    text = tool.run(url)
except ImportError as e:
    if 'python-docx' in str(e):
        text = '[skipped: python-docx not installed]'
    else:
        raise

Prevention

Add python-docx when document URLs are in scope.
Check find_spec('docx') (module name differs from package name) at startup.
Surface missing-parser errors distinctly from fetch errors in logs.

When it happens

Trigger: Calling UrlReadTool on a URL serving a .docx / application/vnd.openxmlformats-officedocument.wordprocessingml.document response without python-docx installed.

Common situations: Minimal crewai-tools installs missing optional document parsers; intranet crawls that encounter Word documents unexpectedly; CI environments trimmed of extras.

Related errors

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