huggingface/transformers · error · ImportError

Missing librosa dependency for audio transcription. Install

Error message

Missing librosa dependency for audio transcription. Install with `pip install librosa`

What it means

An ImportError raised by the transcription handler when transformers.utils.import_utils.is_librosa_available() returns False. Loading and decoding arbitrary audio bytes into model inputs requires librosa, which is an optional dependency, so the server refuses transcription requests until it is installed. Because it is a plain ImportError (not HTTPException) it surfaces as a 500 unless mapped by exception handlers.

Source

Thrown at src/transformers/cli/serving/transcription.py:98

            raise HTTPException(status_code=422, detail=f"Unexpected fields in the request: {unexpected}")
        unused = form_keys & UNUSED_TRANSCRIPTION_FIELDS
        if unused:
            logger.warning_once(f"Ignoring unsupported fields in the request: {unused}")

    async def handle_request(self, request: Request) -> JSONResponse | StreamingResponse:
        """Parse multipart form, run transcription, return result.

        Args:
            request (`Request`): FastAPI request containing multipart form data with
                ``file`` (audio bytes), ``model`` (model ID), and optional ``stream`` flag.

        Returns:
            `JSONResponse | StreamingResponse`: Transcription result or SSE stream.
        """
        from transformers.utils.import_utils import is_librosa_available, is_multipart_available

        if not is_librosa_available():
            raise ImportError("Missing librosa dependency for audio transcription. Install with `pip install librosa`")
        if not is_multipart_available():
            raise ImportError(
                "Missing python-multipart dependency for file uploads. Install with `pip install python-multipart`"
            )

        async with request.form() as form:
            self._validate_request(set(form.keys()))
            file_field = form["file"]
            if isinstance(file_field, str):
                raise HTTPException(status_code=422, detail="Expected file upload, got string")
            file_bytes = await file_field.read()
            model = form["model"]
            if not isinstance(model, str):
                raise HTTPException(status_code=422, detail="Expected model name as string")
            stream = str(form.get("stream", "false")).lower() == "true"

        model_id_and_revision = self.model_manager.process_model_name(model)
        audio_model, audio_processor = self.model_manager.load_model_and_processor(model_id_and_revision)

View on GitHub (pinned to a597f97485)

Solutions

1. Install librosa in the serving environment: pip install librosa
2. Or install the audio extra so all audio deps arrive together: pip install 'transformers[audio]'
3. Add a startup health check that calls is_librosa_available() so the gap is caught before the first request

Example fix

# before
$ pip install transformers fastapi uvicorn
# after
$ pip install 'transformers[audio]' librosa

from transformers.utils.import_utils import is_librosa_available
if not is_librosa_available():
    raise SystemExit('Install librosa (pip install transformers[audio]) before serving transcription')

try:
    resp = requests.post(url, files=form)
except ImportError as e:
    if 'librosa' in str(e):
        subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'librosa'])
        resp = requests.post(url, files=form)

When it happens

Trigger: POST /v1/audio/transcriptions on an environment where librosa is not installed: minimal Docker images, fresh venvs with only 'pip install transformers', or CI environments without the audio extra.

Common situations: Deploying the serving CLI in a slim container without the audio extra; upgrading transformers in an env where librosa was never present; audio dependencies being stripped by dependency resolvers.

Related errors

• Missing python-multipart dependency for file uploads. Instal
• Missing dependencies for serving. Install with `pip install
• Unexpected fields in the request: {unexpected}
• Audio transcription requires sequential generation (not CB)
• Invalid input type. Must be a single audio or a list of audi

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/abf57771858b12c5. Report an issue: GitHub.