unslothai/unsloth · error · SttUnavailableError

Speech-to-text needs PyTorch, Transformers, and PyAV. Run `u

Error message

Speech-to-text needs PyTorch, Transformers, and PyAV. Run `unsloth studio update` to install them.

What it means

SttUnavailableError raised by ensure_stt_available() when importing av, torch, or transformers fails. It marks the Transformers Whisper backend as not installed and tells the user to run `unsloth studio update`; is_available() wraps it to probe capability without raising.

Source

Thrown at studio/backend/core/inference/stt_sidecar.py:285

def _known_whisper_languages() -> Optional[frozenset[str]]:
    """Return Whisper's language codes without constructing/loading a model."""
    try:
        from transformers.models.whisper.tokenization_whisper import LANGUAGES
    except Exception:
        # Transformers unavailable or the constant moved: skip the check.
        return None
    return frozenset(LANGUAGES)


def ensure_stt_available() -> None:
    """Raise when the complete local Whisper backend cannot be imported."""
    try:
        import av  # noqa: F401
        import torch  # noqa: F401
        import transformers  # noqa: F401
    except Exception as exc:
        raise SttUnavailableError(
            "Speech-to-text needs PyTorch, Transformers, and PyAV. "
            "Run `unsloth studio update` to install them."
        ) from exc


def is_available() -> bool:
    """True when the complete local Whisper backend can be imported."""
    try:
        ensure_stt_available()
    except SttUnavailableError:
        return False
    return True


def resolve_model_id(model: Optional[str]) -> str:
    """Resolve a curated id or validate a custom Hugging Face repository."""
    if not model:
        return DEFAULT_STT_MODEL

View on GitHub (pinned to 203007d190)

Solutions

1. Run `unsloth studio update` to install/repair the three packages.
2. Verify the environment: `python -c "import torch, transformers, av"` and read the underlying ImportError chain (the original exception is attached via `from exc`).
3. If a specific import fails (e.g. torch/CUDA), fix that dependency version in the studio environment.
4. Gate features on is_available() so the UI degrades gracefully instead of hitting the raise.

Example fix

```python
# before
result = stt_sidecar.transcribe(audio_bytes)

# after
from studio.backend.core.inference import stt_sidecar

if not stt_sidecar.is_available():
    show_message("Run `unsloth studio update` to enable local speech-to-text.")
else:
    result = stt_sidecar.transcribe(audio_bytes)
```

```python
import importlib.util
missing = [m for m in ("torch", "transformers", "av") if importlib.util.find_spec(m) is None]
if missing:
    show_setup_prompt(missing)  # suggest `unsloth studio update`
```

```python
def stt_backend_available() -> bool:
    """True when the local Whisper backend can run."""
    return stt_sidecar.is_available()
```

```python
try:
    stt_sidecar.ensure_stt_available()
except SttUnavailableError as exc:
    show_error("Run `unsloth studio update` to install speech-to-text deps.", cause=exc.__cause__)
```

When it happens

Trigger: Any call into the Transformers STT backend (ensure_stt_available, model download, transcription) on an environment where PyTorch, Transformers, or PyAV is missing, broken (e.g. CUDA DLL mismatch), or not importable.

Common situations: Partial install or interrupted `unsloth studio update`; a Python upgrade breaking compiled wheels; a venv missing optional extras; importing studio backend outside its bundled environment.

Related errors

• NeMo Data Designer Hugging Face integration is not installed
• GPU selection is unavailable on this host: {exc}
• S3 dataset loading requires boto3. Install it with: pip inst
• RAG unavailable: sqlite-vec extension could not be loaded
• Requested GPU {wanted} but none of them are visible to this

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