unslothai/unsloth · error · ValueError

Video generation needs the 'av' package (PyAV) to encode MP4

Error message

Video generation needs the 'av' package (PyAV) to encode MP4s. Install it with: pip install av

What it means

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

Source

Thrown at studio/backend/core/inference/video.py:489

        detect_video_family(f"{repo_id}/{gguf_filename}")
        if gguf_filename and not family_override
        else None
    )
    if fam is None and gguf_filename and not family_override:
        # A renamed GGUF carries no family token, so resolve via general.architecture. No-backend archs still yield None (a 400).
        arch = _picked_gguf_arch(repo_id, gguf_filename)
        if arch:
            fam = detect_video_family(repo_id, override = arch)
    return fam


def _ensure_mp4_encoder_available() -> None:
    """Fail a load fast when PyAV is missing: the export otherwise dies AFTER a
    multi-minute denoise, which is the worst possible time to learn about it."""
    try:
        import av  # noqa: F401
    except Exception as exc:  # noqa: BLE001 -- any import failure means no encoder
        raise ValueError(
            "Video generation needs the 'av' package (PyAV) to encode MP4s. "
            "Install it with: pip install av"
        ) from exc


@dataclass(frozen = True)
class _VideoLoadState:
    """Everything about the currently-loaded video pipeline, swapped as one unit."""

    pipe: Any
    family: VideoFamily
    repo_id: str
    base_repo: str
    device: str
    dtype: str
    kind: str
    engine: str = "diffusers"
    # The torch ordinal this pipeline's weights were placed on, or None for an automatic pick.

View on GitHub (pinned to 203007d190)

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.

Example fix

# before: env lacks PyAV, generation dies at export time (or is refused at load)

# after
pip install av
# verify:
python -c 'import av; print(av.__version__)'

Defensive patterns

Strategy: validation

Validate before calling

def mp4_encoder_available() -> bool:
    try:
        import av  # noqa: F401
        return True
    except Exception:
        return False

Try / catch

try:
    load_video_model(repo_id=r)
except ValueError as e:
    if "'av' package" in str(e):
        raise SetupError('Run: pip install av') from e
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/104214d8a4c264a3. Report an issue: GitHub.