crewAIInc/crewAI · error · ImportError

YouTube support requires youtube-transcript-api. Install wit

Error message

YouTube support requires youtube-transcript-api. Install with: uv add youtube-transcript-api

What it means

ImportError raised by the YouTube video loader when the optional youtube-transcript-api package is missing. Like the channel loader, the import happens inside load(), so the error surfaces only when a YouTube video source is actually loaded. The message includes the exact uv add command.

Source

Thrown at lib/crewai-tools/src/crewai_tools/rag/loaders/youtube_video_loader.py:30

    """Loader for YouTube videos."""

    def load(self, source: SourceContent, **kwargs: Any) -> LoaderResult:  # type: ignore[override]
        """Load and extract transcript from a YouTube video.

        Args:
            source: The source content containing the YouTube URL

        Returns:
            LoaderResult with transcript content

        Raises:
            ImportError: If required YouTube libraries aren't installed
            ValueError: If the URL is not a valid YouTube video URL
        """
        try:
            from youtube_transcript_api import YouTubeTranscriptApi
        except ImportError as e:
            raise ImportError(
                "YouTube support requires youtube-transcript-api. "
                "Install with: uv add youtube-transcript-api"
            ) from e

        video_url = source.source
        video_id = self._extract_video_id(video_url)

        if not video_id:
            raise ValueError(f"Invalid YouTube URL: {video_url}")

        metadata: dict[str, Any] = {
            "source": video_url,
            "video_id": video_id,
            "data_type": "youtube_video",
        }

        try:
            api = YouTubeTranscriptApi()

View on GitHub (pinned to 754d7323be)

Solutions

Run: uv add youtube-transcript-api (or pip install youtube-transcript-api) in the executing environment.
Verify: python -c "from youtube_transcript_api import YouTubeTranscriptApi; print('ok')" using the same interpreter that runs your app.
Pin the dependency in pyproject/requirements so deployments install it automatically.
For channel loading you may also want pytube — the two YouTube loaders have separate optional deps.

Example fix

# shell
# before: package missing
# after:
# uv add youtube-transcript-api
result = yt_video_loader.load(SourceContent(path="https://www.youtube.com/watch?v=..."))

Defensive patterns

Strategy: validation

Validate before calling

def transcript_api_available() -> bool:
    try:
        from youtube_transcript_api import YouTubeTranscriptApi  # noqa: F401
        return True
    except ImportError:
        return False

Try / catch

try:
    result = yt_video_loader.load(src)
except ImportError as e:
    if "youtube-transcript-api" in str(e):
        disable_youtube_sources()
    raise

Prevention

Add youtube-transcript-api to your project's dependencies if you ingest video transcripts.
Check optional imports at startup and feature-flag YouTube ingestion accordingly.
Verify installs with the same interpreter that runs the app, not a different venv.

When it happens

Trigger: Calling youtube_video_loader.load(...) in an environment without youtube-transcript-api installed — base crewai-tools install without the YouTube extras, a fresh venv, or a Docker image that predates the dependency.

Common situations: Local dev works but CI/deployment fails because the extra was only installed ad hoc locally; multiple virtualenvs and the tool running under a different interpreter; dependency resolver removed the package after a conflict.

Related errors

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