Graphify-Labs/graphify · error · ImportError

YouTube/URL download requires yt-dlp. Run: pip install 'grap

Error message

YouTube/URL download requires yt-dlp. Run: pip install 'graphifyy[video]'

What it means

Raised by _get_yt_dlp (graphify/transcribe.py) when `import yt_dlp` fails. Downloading audio from a YouTube/URL source is optional functionality behind the [video] extra; the import is lazy, so the error appears only at the moment a URL download is attempted (is_url(path) returned True).

Source

Thrown at graphify/transcribe.py:39


def _get_whisper():
    try:
        from faster_whisper import WhisperModel
        return WhisperModel
    except ImportError as exc:
        raise ImportError(
            "Video transcription requires faster-whisper. "
            "Run: pip install 'graphifyy[video]'"
        ) from exc


def _get_yt_dlp():
    try:
        import yt_dlp
        return yt_dlp
    except ImportError as exc:
        raise ImportError(
            "YouTube/URL download requires yt-dlp. "
            "Run: pip install 'graphifyy[video]'"
        ) from exc


def is_url(path: str) -> bool:
    """Return True if the string looks like a URL rather than a file path."""
    return any(path.startswith(p) for p in URL_PREFIXES)


def download_audio(url: str, output_dir: Path) -> Path:
    """Download audio-only stream from a URL using yt-dlp.

    Returns the path to the downloaded audio file (.m4a or .opus).
    Uses cached file if already downloaded.
    """
    from graphify.security import validate_url
    validate_url(url)  # blocks private IPs, bad schemes before yt-dlp runs

View on GitHub (pinned to 7fe58b0b0f)

Solutions

pip install 'graphifyy[video]' to get yt-dlp (and faster-whisper).
Or download the media yourself beforehand and pass the local file path, which bypasses _get_yt_dlp entirely.
Keep yt-dlp current — site changes frequently break old versions (python -m pip install -U yt-dlp).
If installs are blocked, host the audio file internally and reference it by path.

Example fix

# before
transcribe("https://youtu.be/xyz123")  # ImportError: yt-dlp missing

# after
pip install 'graphifyy[video]'
transcribe("https://youtu.be/xyz123")
# or: download manually, then
transcribe("talk.m4a")

Defensive patterns

Strategy: validation

Validate before calling

def yt_dlp_available() -> bool:
    try:
        import yt_dlp  # noqa: F401
    except ImportError:
        return False
    return True

from graphify.transcribe import is_url
if is_url(target) and not yt_dlp_available():
    raise SystemExit("URL download needs: pip install 'graphifyy[video]' (or pass a local file)")

Type guard

def can_download_urls() -> bool:
    return yt_dlp_available()

Try / catch

try:
    audio = download_audio(url, out_dir)
except ImportError as e:
    if 'yt-dlp' in str(e):
        # explicit alternative: user downloads media, we take a local path
        audio = Path(ask_user_for_local_file())
    else:
        raise

Prevention

Install the [video] extra where URL ingestion is used.
Accept local file paths as a fallback input path in pipelines.
Keep yt-dlp updated; old versions fail on site changes.

When it happens

Trigger: Calling download_audio(url, ...) or transcription on a string starting with one of URL_PREFIXES in an environment without yt-dlp installed.

Common situations: Base graphifyy install used with URL input; environments that block yt-dlp installs (some corporate mirrors); yt-dlp removed by a cleanup step after it broke on a site change.

Related errors

AI-assisted analysis of Graphify-Labs/graphify@7fe58b0b0f (2026-08-14). Data as JSON: /api/errors/530d3e268ff521d9. Report an issue: GitHub.