huggingface/transformers · error · ImportError

Missing python-multipart dependency for file uploads. Instal

Error message

Missing python-multipart dependency for file uploads. Install with `pip install python-multipart`

What it means

An ImportError raised by the transcription handler when python-multipart is missing. FastAPI's request.form() multipart parsing is delegated to the python-multipart package, which is not installed with FastAPI by default, so file uploads cannot be parsed without it. It is a plain ImportError, so clients typically see a 500 unless mapped.

Source

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

        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)
        base_manager = self.generation_state.get_manager(model_id_and_revision)
        if not isinstance(base_manager, GenerateManager):

View on GitHub (pinned to a597f97485)

Solutions

  1. Install python-multipart: pip install python-multipart
  2. Or reinstall fastapi with the standard extras: pip install 'fastapi[standard]'
  3. Pin python-multipart explicitly in requirements.txt so pruning tools keep it

Example fix

# before
$ pip install fastapi uvicorn
# after
$ pip install fastapi 'fastapi[standard]' python-multipart
Defensive patterns

Strategy: validation

Validate before calling

from transformers.utils.import_utils import is_multipart_available
if not is_multipart_available():
    raise SystemExit('Install python-multipart before uploading files')

Try / catch

try:
    resp = requests.post(url, files=form)
except ImportError as e:
    if 'python-multipart' in str(e):
        raise RuntimeError('server env lacks python-multipart; pip install python-multipart') from e

Prevention

When it happens

Trigger: POST /v1/audio/transcriptions with multipart file data on an environment lacking python-multipart. Requests to other endpoints work fine, which makes the failure look endpoint-specific.

Common situations: Installing fastapi without the standard 'pip install fastapi[standard]' bundle; slim production images that prune 'optional' packages; venvs built from a requirements list that omits python-multipart.

Related errors

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