{"id":"93df0e4177ef02d2","repo":"tiangolo/fastapi","slug":"form-data-requires-python-multipart-to-be-instal","errorCode":null,"errorMessage":"Form data requires \"python-multipart\" to be installed. It seems you installed \"multipart\" instead. \nYou can remove \"multipart\" with: \n\npip uninstall multipart\n\nAnd then install \"python-multipart\" with: \n\npip install python-multipart\n","messagePattern":"Form data requires \"python-multipart\" to be installed\\. It seems you installed \"multipart\" instead\\. \nYou can remove \"multipart\" with: \n\npip uninstall multipart\n\nAnd then install \"python-multipart\" with: \n\npip install python-multipart\n","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"fastapi/dependencies/utils.py","lineNumber":126,"sourceCode":"        assert __version__ > \"0.0.12\"\n    except (ImportError, AssertionError):\n        try:\n            # __version__ is available in both multiparts, and can be mocked\n            from multipart import (  # type: ignore[no-redef,import-untyped]\n                __version__,\n            )\n\n            assert __version__\n            try:\n                # parse_options_header is only available in the right multipart\n                from multipart.multipart import (  # type: ignore[import-untyped]\n                    parse_options_header,\n                )\n\n                assert parse_options_header\n            except ImportError:\n                logger.error(multipart_incorrect_install_error)\n                raise RuntimeError(multipart_incorrect_install_error) from None\n        except ImportError:\n            logger.error(multipart_not_installed_error)\n            raise RuntimeError(multipart_not_installed_error) from None\n\n\ndef get_parameterless_sub_dependant(*, depends: params.Depends, path: str) -> Dependant:\n    assert callable(depends.dependency), (\n        \"A parameter-less dependency must have a callable dependency\"\n    )\n    own_oauth_scopes: list[str] = []\n    if isinstance(depends, params.Security) and depends.scopes:\n        own_oauth_scopes.extend(depends.scopes)\n    return get_dependant(\n        path=path,\n        call=depends.dependency,\n        scope=depends.scope,\n        own_oauth_scopes=own_oauth_scopes,\n    )","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/tiangolo/fastapi/blob/42a41db11f6882807ac3c057b942178d53b97438/fastapi/dependencies/utils.py#L108-L144","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Uninstall the wrong package and install the right one: pip uninstall multipart && pip install python-multipart.","Pin python-multipart (>=0.0.18) in requirements.txt/pyproject.toml.","Rebuild the virtualenv/Docker image after fixing requirements to clear stale installs.","Verify with: python -c 'from multipart.multipart import parse_options_header; print(parse_options_header)'."],"exampleFix":"# before\npip install multipart\n# after\npip uninstall multipart\npip install python-multipart","handlingStrategy":"validation","validationCode":"import importlib.util, sys, subprocess\nok = importlib.util.find_spec('python_multipart') is not None\nif not ok:\n    if importlib.util.find_spec('multipart') is not None:\n        subprocess.check_call([sys.executable, '-m', 'pip', 'uninstall', '-y', 'multipart'])\n    subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'python-multipart'])\nfrom multipart.multipart import parse_options_header  # verifies correct package","typeGuard":"def correct_multipart_installed() -> bool:\n    try:\n        from multipart.multipart import parse_options_header  # noqa: F401\n        return True\n    except ImportError:\n        return False","tryCatchPattern":"from fastapi.dependencies.utils import ensure_multipart_is_installed\ntry:\n    ensure_multipart_is_installed()\nexcept RuntimeError:\n    import subprocess, sys\n    subprocess.check_call([sys.executable, '-m', 'pip', 'uninstall', '-y', 'multipart'])\n    subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'python-multipart'])","preventionTips":["Install python-multipart, never the bare `multipart` package.","Pin python-multipart in requirements.txt/pyproject.toml.","Verify with: python -c 'from multipart.multipart import parse_options_header'.","Rebuild the venv/image after fixing requirements to clear the wrong package."],"tags":["multipart","forms","installation","packaging","fastapi"],"analyzedSha":"42a41db11f6882807ac3c057b942178d53b97438","analyzedAt":"2026-08-04T19:23:32.007Z","schemaVersion":2}