tiangolo/fastapi · critical · RuntimeError

Form data requires "python-multipart" to be installed. It se

Error message

Form data requires "python-multipart" to be installed. It seems you installed "multipart" instead. 
You can remove "multipart" with: 

pip uninstall multipart

And then install "python-multipart" with: 

pip install python-multipart

What it means

RuntimeError raised by ensure_multipart_is_installed() at dependencies/utils.py:126 when form-data handling is needed but the wrong package `multipart` (not `python-multipart`) is installed. The detection imports python_multipart first; on failure it imports `multipart` and then tries `from multipart.multipart import parse_options_header`; if that ImportError occurs it logs multipart_incorrect_install_error and raises RuntimeError. The two packages share the top-level name but only python-multipart has parse_options_header.

Source

Thrown at fastapi/dependencies/utils.py:126

        assert __version__ > "0.0.12"
    except (ImportError, AssertionError):
        try:
            # __version__ is available in both multiparts, and can be mocked
            from multipart import (  # type: ignore[no-redef,import-untyped]
                __version__,
            )

            assert __version__
            try:
                # parse_options_header is only available in the right multipart
                from multipart.multipart import (  # type: ignore[import-untyped]
                    parse_options_header,
                )

                assert parse_options_header
            except ImportError:
                logger.error(multipart_incorrect_install_error)
                raise RuntimeError(multipart_incorrect_install_error) from None
        except ImportError:
            logger.error(multipart_not_installed_error)
            raise RuntimeError(multipart_not_installed_error) from None


def get_parameterless_sub_dependant(*, depends: params.Depends, path: str) -> Dependant:
    assert callable(depends.dependency), (
        "A parameter-less dependency must have a callable dependency"
    )
    own_oauth_scopes: list[str] = []
    if isinstance(depends, params.Security) and depends.scopes:
        own_oauth_scopes.extend(depends.scopes)
    return get_dependant(
        path=path,
        call=depends.dependency,
        scope=depends.scope,
        own_oauth_scopes=own_oauth_scopes,
    )

View on GitHub (pinned to 42a41db11f)

Solutions

1. Uninstall the wrong package and install the right one: pip uninstall multipart && pip install python-multipart.
2. Pin python-multipart (>=0.0.18) in requirements.txt/pyproject.toml.
3. Rebuild the virtualenv/Docker image after fixing requirements to clear stale installs.
4. Verify with: python -c 'from multipart.multipart import parse_options_header; print(parse_options_header)'.

Example fix

# before
pip install multipart
# after
pip uninstall multipart
pip install python-multipart

import importlib.util, sys, subprocess
ok = importlib.util.find_spec('python_multipart') is not None
if not ok:
    if importlib.util.find_spec('multipart') is not None:
        subprocess.check_call([sys.executable, '-m', 'pip', 'uninstall', '-y', 'multipart'])
    subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'python-multipart'])
from multipart.multipart import parse_options_header  # verifies correct package

def correct_multipart_installed() -> bool:
    try:
        from multipart.multipart import parse_options_header  # noqa: F401
        return True
    except ImportError:
        return False

from fastapi.dependencies.utils import ensure_multipart_is_installed
try:
    ensure_multipart_is_installed()
except RuntimeError:
    import subprocess, sys
    subprocess.check_call([sys.executable, '-m', 'pip', 'uninstall', '-y', 'multipart'])
    subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'python-multipart'])

When it happens

Trigger: Declaring any Form() / File() / UploadFile parameter (which triggers form parsing) in an environment where `pip install multipart` was run instead of `pip install python-multipart`. The first form-handling request (or app startup building the request model) hits ensure_multipart_is_installed and fails the parse_options_header import.

Common situations: Following an old blog that says `pip install multipart`; CI cache installing the wrong package; a transitive dep pulling in `multipart`; case/typo confusion between the two similarly named packages.

Related errors

• Form data requires "python-multipart" to be installed. You
• To use the fastapi command, please install "fastapi[standard
• Expected UploadFile, received: {type(__input_value)}
• Invalid X-Token header
• Item not found

AI-assisted analysis of tiangolo/fastapi@42a41db11f (2026-08-04). Data as JSON: /data/errors/93df0e4177ef02d2.json. Report an issue: GitHub.