できない.dev

FastAPI「Form data requires "python-multipart"」の原因と直し方

Form data requires "python-multipart" to be installed は、pip install python-multipart で直る。
Form や UploadFile を使うと起動時に必要になる。
似た名前の multipart は先に外す。

公開: 更新:

症状できない · exit 1
python -m pip show python-multipart
WARNING: Package(s) not found: python-multipart

2026-11-03 に python:3.12（Python 3.12.16 / Git 2.47.3） で実際に打って取った出力。検証環境の詳細

要約

Form() でフォームの値を受け取るルートを書いたところ、リクエストを送る前、アプリを読み込んだ時点で止まった。
FastAPI 0.156.4（Python 3.12）では次のように出た。

Form data requires "python-multipart" to be installed. 
You can install "python-multipart" with: 
 
pip install python-multipart
 
Traceback (most recent call last):
  ...
RuntimeError: Form data requires "python-multipart" to be installed.

Form data requires "python-multipart" は、フォームやファイルを解析するパッケージ python-multipart が入っていないという意味だ。
FastAPI はルートを登録するときに、引数に Form()・File()・UploadFile があるとこのパッケージを読み込もうとする。
そのため uvicorn main:app の起動そのものが失敗する。
公式チュートリアルのForm Data（新しいタブで開く）でも、フォームを使う前に python-multipart を入れるよう案内している。

実行例

python-multipart を入れていない python:3.12 の環境では、uvicorn main:app も uvicorn upload:app も同じ RuntimeError で止まった。multipart を入れた場合は、メッセージが It seems you installed "multipart" instead. を含む文面に変わった。multipart を外して python-multipart を入れると、/login へのフォーム送信に username の値を含む JSON が返った。

$ uvicorn main:app 2>&1 | tail -n 10
                    ^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/site-packages/fastapi/dependencies/utils.py", line 563, in analyze_param
    ensure_multipart_is_installed()
  File "/usr/local/lib/python3.12/site-packages/fastapi/dependencies/utils.py", line 141, in ensure_multipart_is_installed
    raise RuntimeError(multipart_not_installed_error) from None
RuntimeError: Form data requires "python-multipart" to be installed. 
You can install "python-multipart" with: 
 
pip install python-multipart
$ uvicorn upload:app 2>&1 | tail -n 10
                    ^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/site-packages/fastapi/dependencies/utils.py", line 563, in analyze_param
    ensure_multipart_is_installed()
  File "/usr/local/lib/python3.12/site-packages/fastapi/dependencies/utils.py", line 141, in ensure_multipart_is_installed
    raise RuntimeError(multipart_not_installed_error) from None
RuntimeError: Form data requires "python-multipart" to be installed. 
You can install "python-multipart" with: 
 
pip install python-multipart
$ python -m pip show python-multipart
WARNING: Package(s) not found: python-multipart
$ echo $?
1
$ pip install multipart
Collecting multipart
  Downloading multipart-2.0.1-py3-none-any.whl.metadata (4.5 kB)
Downloading multipart-2.0.1-py3-none-any.whl (16 kB)
Installing collected packages: multipart
Successfully installed multipart-2.0.1
$ uvicorn main:app 2>&1 | tail -n 10
    raise RuntimeError(multipart_incorrect_install_error) from None
RuntimeError: 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
$ pip uninstall -y multipart
Found existing installation: multipart 2.0.1
Uninstalling multipart-2.0.1:
  Successfully uninstalled multipart-2.0.1
$ pip install python-multipart
Collecting python-multipart
  Downloading python_multipart-0.0.33-py3-none-any.whl.metadata (6.3 kB)
Downloading python_multipart-0.0.33-py3-none-any.whl (32 kB)
Installing collected packages: python-multipart
Successfully installed python-multipart-0.0.33
$ uvicorn main:app --port 8000 > server.log 2>&1 &
$ curl -s -X POST -d "username=user&password=x" http://127.0.0.1:8000/login
{"username":"user"}

— 2026-11-03 時点の出力

検証環境Python 3.12.16 / Git 2.47.3 / 2026-11-03 検証
検証日
実行環境
python:3.12 Debian GNU/Linux 13 (trixie)
バージョン
  • Python 3.12.16
  • Git 2.47.3

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. python-multipart を入れる

pip install python-multipart

入れた後は同じ main.py が読み込めるようになり、curl -X POST -d 'username=user&password=x' http://127.0.0.1:8000/login に {"username":"user"} が返った。
依存の一覧にも書いておかないと、別の環境で同じエラーが出る。

2. fastapi[standard] でまとめて入れる

pip install "fastapi[standard]"

fastapi[standard] で入れると python-multipart も一緒に入り、UploadFile を使うルートもそのまま読み込めた。

3. multipart を入れてしまったときは外してから入れる

pip uninstall multipart
pip install python-multipart

4. 動かしている Python で確かめる

python -m pip show python-multipart

python -m pip は、その python の環境を見る。WARNING: Package(s) not found: python-multipart と出て終了コードが 1 なら、その環境には入っていない。

なお、フォームを受け取るルートに JSON を送ると、このエラーではなく 422 になる。Form() の項目は JSON のボディからは読まれず、Field required が返った。

よくある原因

  1. python-multipart を入れていない。pip install fastapi だけでは入らない。UploadFile だけを使うルートでも同じエラーになった。
  2. 似た名前の multipart を入れた。pip install multipart で入る別のパッケージだと、メッセージが It seems you installed "multipart" instead. に変わり、pip uninstall multipart を促される。
  3. 入れた環境が違う。
    venv の外や別のコンテナに入れていて、uvicorn を動かす Python からは見えていない。
#fastapi #python-multipart #form #uploadfile #runtimeerror