Graphify-Labs/graphify · error · ImportError

Video transcription requires faster-whisper. Run: pip instal

Error message

Video transcription requires faster-whisper. Run: pip install 'graphifyy[video]'

What it means

Raised by _get_whisper (graphify/transcribe.py) when `from faster_whisper import WhisperModel` fails. Video transcription is optional functionality gated behind the [video] extra, so the import is deferred until actually needed and this ImportError tells you the extra was not installed. The original ImportError is chained as __cause__.

Source

Thrown at graphify/transcribe.py:28

VIDEO_EXTENSIONS = {'.mp4', '.mov', '.webm', '.mkv', '.avi', '.m4v', '.mp3', '.wav', '.m4a', '.ogg'}
URL_PREFIXES = ('http://', 'https://', 'www.')

_DEFAULT_MODEL = "base"
_TRANSCRIPTS_DIR = str(_out_path("transcripts"))
_FALLBACK_PROMPT = "Use proper punctuation and paragraph breaks."


def _model_name() -> str:
    return os.environ.get("GRAPHIFY_WHISPER_MODEL", _DEFAULT_MODEL)


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."""

View on GitHub (pinned to 7fe58b0b0f)

Solutions

pip install 'graphifyy[video]' exactly as the message says.
If you only need audio from URLs, still install the same extra (it also provides yt-dlp).
On constrained machines verify the install succeeded: python -c "from faster_whisper import WhisperModel".
If the import fails despite install, check for ctranslate2/tokenizers binary-incompatibility errors in the chained cause.

Example fix

# before
pip install graphifyy
transcribe("demo.mp4")  # ImportError

# after
pip install 'graphifyy[video]'
transcribe("demo.mp4")

Defensive patterns

Strategy: validation

Validate before calling

def whisper_available() -> bool:
    try:
        from faster_whisper import WhisperModel  # noqa: F401
    except ImportError:
        return False
    return True

if path.endswith((".mp4", ".mkv", ".webm")) and not whisper_available():
    raise SystemExit("video support missing: pip install 'graphifyy[video]'")

Type guard

def can_transcribe_video() -> bool:
    return whisper_available()

Try / catch

try:
    text = transcribe(media_path)
except ImportError as e:
    if 'graphifyy[video]' in str(e):
        raise SystemExit("Video extra not installed. Run: pip install 'graphifyy[video]'") from e
    raise

Prevention

Install 'graphifyy[video]' on any node that ingests video.
Feature-flag video ingestion behind an availability check.
Test the faster_whisper import in environment validation scripts.

When it happens

Trigger: Calling any transcription API that goes through _get_whisper (e.g. transcribing a local video file) in an environment where faster-whisper is not installed.

Common situations: Base install pip install graphifyy then attempting video ingestion; CPU-only machines where faster-whisper was skipped to avoid pulling CUDA wheels; CI environments trimmed to minimum deps.

Related errors

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