{"record":{"id":"104214d8a4c264a3","repo":"unslothai/unsloth","slug":"video-generation-needs-the-av-package-pyav-to","errorCode":null,"errorMessage":"Video generation needs the 'av' package (PyAV) to encode MP4s. Install it with: pip install av","messagePattern":"Video generation needs the 'av' package \\(PyAV\\) to encode MP4s\\. Install it with: pip install av","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"studio/backend/core/inference/video.py","lineNumber":489,"sourceCode":"        detect_video_family(f\"{repo_id}/{gguf_filename}\")\n        if gguf_filename and not family_override\n        else None\n    )\n    if fam is None and gguf_filename and not family_override:\n        # A renamed GGUF carries no family token, so resolve via general.architecture. No-backend archs still yield None (a 400).\n        arch = _picked_gguf_arch(repo_id, gguf_filename)\n        if arch:\n            fam = detect_video_family(repo_id, override = arch)\n    return fam\n\n\ndef _ensure_mp4_encoder_available() -> None:\n    \"\"\"Fail a load fast when PyAV is missing: the export otherwise dies AFTER a\n    multi-minute denoise, which is the worst possible time to learn about it.\"\"\"\n    try:\n        import av  # noqa: F401\n    except Exception as exc:  # noqa: BLE001 -- any import failure means no encoder\n        raise ValueError(\n            \"Video generation needs the 'av' package (PyAV) to encode MP4s. \"\n            \"Install it with: pip install av\"\n        ) from exc\n\n\n@dataclass(frozen = True)\nclass _VideoLoadState:\n    \"\"\"Everything about the currently-loaded video pipeline, swapped as one unit.\"\"\"\n\n    pipe: Any\n    family: VideoFamily\n    repo_id: str\n    base_repo: str\n    device: str\n    dtype: str\n    kind: str\n    engine: str = \"diffusers\"\n    # The torch ordinal this pipeline's weights were placed on, or None for an automatic pick.","sourceCodeStart":471,"sourceCodeEnd":507,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/core/inference/video.py#L471-L507","documentation":"_ensure_mp4_encoder_available fails fast when 'import av' raises: PyAV is the MP4 muxing backend for video export, and without it a generation would only die after the multi-minute denoise finishes. Any import failure (missing wheel, broken install, missing FFmpeg libs) counts, hence the broad except.","triggerScenarios":"Running video generation on an environment where the av package is absent or unimportable — fresh venv without av, an av wheel built against a system FFmpeg that was upgraded/removed, or a stripped container image.","commonSituations":"Docker images that skip the av dependency; upgrading system FFmpeg breaking a source-built PyAV; Windows machines missing the bundled FFmpeg DLLs; headless servers where av was never installed.","solutions":["Install PyAV: pip install av (prefer a prebuilt wheel matching your Python version).","If a source build is unavoidable, install FFmpeg development headers first, then rebuild av.","In containers, add the av package to the image rather than relying on the host."],"exampleFix":"# before: env lacks PyAV, generation dies at export time (or is refused at load)\n\n# after\npip install av\n# verify:\npython -c 'import av; print(av.__version__)'","handlingStrategy":"validation","validationCode":"def mp4_encoder_available() -> bool:\n    try:\n        import av  # noqa: F401\n        return True\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    load_video_model(repo_id=r)\nexcept ValueError as e:\n    if \"'av' package\" in str(e):\n        raise SetupError('Run: pip install av') from e\n    raise","preventionTips":["Add av to requirements/pyproject for any deployment that generates MP4s.","Smoke-test 'import av' in container health checks.","After system FFmpeg upgrades, reinstall PyAV so its linkage matches."],"tags":["video","dependencies","pyav","ffmpeg"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}