Contents
FastAPI CLI のインストールと fastapi dev の概要
FastAPI アプリのローカル開発では、公式が提供する fastapi‑cli を利用すれば fastapi dev コマンドで即座にサーバを起動できます。
本節では、インストール手順・依存関係の確認方法と、コマンドの基本的な使い方を解説します。
インストール方法と依存関係の確認
fastapi[all] には fastapi‑cli が含まれていることが公式ドキュメントで明記されています（Installation – FastAPI）。このオプションを使うと、FastAPI 本体に加えて推奨されるすべての依存パッケージが一括でインストールされます。
|
1 2 3 |
# 推奨インストールコマンド（fastapi 本体 + すべての推奨依存 + fastapi‑cli） pip install "fastapi[all]" |
- 補足情報
fastapi-cliの実装は公式リポジトリのfastapi/cliディレクトリにあります → https://github.com/tiangolo/fastapi/tree/master/fastapi/cli- Qiita の実装例だけでなく、FastAPI の公式チュートリアルでも同様の手順が紹介されています。
fastapi dev の基本的な使い方
インストール後にターミナルで fastapi --help を実行すると、dev サブコマンドが一覧に表示されます。最もシンプルな起動例は次の通りです。
|
1 2 3 |
# アプリ本体が記述されたファイルを直接指定して起動 fastapi dev main.py |
このコマンドは内部で uvicorn を呼び出し、コード変更時に自動リロード（--reload）がデフォルトで有効になります。
エントリポイントの指定方法とベストプラクティス
FastAPI アプリをパッケージ化した場合やテスト環境で複数モジュールを利用する際は、エントリポイントを明示的に指定することが推奨されます。ここではファイル単体の起動例と --entrypoint オプションの使い方を比較します。
ファイル単体での起動例
シンプルなスクリプト（例: main.py）だけで構成されたプロジェクトは、ファイル名をそのまま渡すだけで起動できます。公式チュートリアルでも同様の記述があります【最初のステップ – FastAPI】。
|
1 2 |
fastapi dev main.py |
--entrypoint オプションでモジュールパスを指定
プロジェクトがサブディレクトリに分割されている場合や、FastAPI インスタンスの名前が app 以外の場合は package.module:object 形式でエントリポイントを指示します。
|
1 2 3 |
# 例: myproject/app/api.py にある FastAPI インスタンス `application` を起動 fastapi dev --entrypoint app.api:application |
この指定により、モジュール探索パスが変わっても正しくインポートできるため、Docker や CI 環境でも安定した挙動が期待できます。
開発サーバーの設定オプション（リロード・ホスト・ポート）
ローカル開発ではコード変更のたびに自動で再起動させたり、外部からコンテナへアクセスできるようにホストやポートを調整したりすることが頻繁です。fastapi dev はそれらをフラグと環境変数で柔軟に制御できます。
リロード機能の制御
自動リロードはデフォルトで有効（--reload）ですが、必要に応じて無効化できます。以下の表は主なフラグとその既定値を示します。
| フラグ | デフォルト | 例 |
|---|---|---|
--reload / --no-reload |
有効 (--reload) |
fastapi dev main.py --no-reload |
--host |
127.0.0.1 |
fastapi dev main.py --host 0.0.0.0 |
--port |
8000 |
fastapi dev main.py --port 8080 |
ホスト・ポートの指定と環境変数連携
Docker や社内ネットワークで外部からアクセスさせる場合は、ホストを 0.0.0.0 に設定し、必要に応じてポート番号も変更します。環境変数 FASTAPI_HOST・FASTAPI_PORT と組み合わせると、スクリプトの可搬性が向上します。
|
1 2 3 4 5 |
export FASTAPI_HOST=0.0.0.0 export FASTAPI_PORT=8080 fastapi dev main.py --host $FASTAPI_HOST --port $FASTAPI_PORT |
複数エントリーポイントやパッケージ構成での運用指針
大規模プロジェクトでは、アプリ本体をサブモジュールに分割し、テストコードから同一インスタンスを参照するケースが増えます。ここでは推奨されるディレクトリ構造とエントリポイント設定のベストプラクティスを示します。
ディレクトリ構造例とエントリポイント設定
以下は典型的な FastAPI パッケージ構成です。app/main.py に FastAPI インスタンスを定義し、サブパッケージのルーターを組み込みます。
|
1 2 3 4 5 6 7 8 9 |
myproject/ ├─ app/ │ ├─ __init__.py │ ├─ main.py # ← エントリーポイント（app:FastAPI） │ └─ routers/ │ └─ user.py └─ tests/ └─ test_user.py |
myproject/app/main.py
|
1 2 3 4 5 6 |
from fastapi import FastAPI from .routers import user app = FastAPI() app.include_router(user.router) |
起動コマンドは次のように記述します。
|
1 2 |
fastapi dev --entrypoint app.main:app |
テストコードとの統一
テストからも同じインスタンスを利用すれば、開発サーバとテスト環境で挙動が一致します。pytest での典型的な書き方は以下です。
|
1 2 3 4 5 6 7 8 9 |
from fastapi.testclient import TestClient from app.main import app client = TestClient(app) def test_ping(): response = client.get("/ping") assert response.status_code == 200 |
エントリポイントを絶対モジュールパスで指定することで、実行ディレクトリが変わってもインポートエラーが発生しにくくなります。
Docker 環境で fastapi dev を活用する方法
コンテナ内開発ではボリュームマウントとホットリロードが鍵です。fastapi dev はそのまま Dockerfile に組み込めるため、ローカルと同様の体験が可能です。
Dockerfile の作成例
以下は最小構成の Dockerfile です。fastapi[all] をインストールすることで fastapi-cli が自動的に含まれます。
|
1 2 3 4 5 6 7 8 9 10 11 |
FROM python:3.11-slim WORKDIR /app # 依存関係だけを先に取得（キャッシュ活用のため） COPY pyproject.toml poetry.lock ./ RUN pip install "fastapi[all]" # ソースコードはコンテナ起動時にマウントするのでコピーしない CMD ["fastapi", "dev", "--host", "0.0.0.0", "--port", "8000"] |
docker‑compose.yml とボリュームマウント設定
docker compose を使うと、コード変更が即座にコンテナ内サーバへ反映されます。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
version: "3.9" services: api: build: . volumes: - ./:/app # ソースコードをリアルタイムで共有 ports: - "8000:8000" environment: FASTAPI_HOST: 0.0.0.0 FASTAPI_PORT: 8000 |
起動手順は次の通りです。
|
1 2 |
docker compose up --build |
この状態でローカルの app/main.py を編集すると、コンテナ内の開発サーバが自動リロードされます。
トラブルシューティングと uvicorn との比較
fastapi dev は便利ですが、環境依存のエラーに遭遇することもあります。本節では代表的な問題例と対処法、そして uvicorn --reload との選択基準をまとめます。
よくあるエラーと対処法
| エラー | 主な原因 | 推奨対策 |
|---|---|---|
fastapi: command not found |
PATH に ~/.local/bin が含まれていない、またはインストールが失敗している |
pip install "fastapi[all]" を再実行し、export PATH=$HOME/.local/bin:$PATH |
ImportError: cannot import name 'app' from 'main' |
エントリポイント指定ミスや相対インポートの誤り | --entrypoint main:app の形式で正しく指す。パッケージ化している場合は絶対モジュールパスに変更 |
Address already in use (ポート競合) |
同一ホストで別プロセスが同ポートを使用中 | --port を別番号に変えるか、lsof -i:8000 で占有プロセスを特定し停止 |
公式ドキュメントのエラーページ（FastAPI – Troubleshooting）でも同様の情報が提供されています。
fastapi dev と uvicorn --reload の選択基準
| 条件 | 推奨コマンド |
|---|---|
| 手早くシンプルなスクリプトを起動したい | fastapi dev main.py |
| カスタム uvicorn オプション（ログレベルやバックグラウンドタスク）を細かく制御したい | uvicorn app.main:app --reload --log-level debug |
| 複数エントリーポイント・Docker 環境で一貫した CLI を使いたい | fastapi dev --entrypoint package.module:app |
fastapi dev は内部的に uvicorn をラップしているため、基本的な機能は同等です。プロジェクトの規模や運用方針に合わせて使い分けると良いでしょう。
参考リンク
-
FastAPI 公式インストールガイド
https://fastapi.tiangolo.com/ja/tutorial/installation/#install-fastapi-with-all-dependencies -
fastapi‑cli ソースコード（GitHub）
https://github.com/tiangolo/fastapi/tree/master/fastapi/cli -
FastAPI チュートリアル – 最初のステップ
https://fastapi.tiangolo.com/ja/tutorial/first-steps/ -
トラブルシューティングページ
https://fastapi.tiangolo.com/ja/troubleshooting/ -
Qiita 実装例（参考）
https://qiita.com/zumax/items/7684e7f06b06e8960702
以上で、fastapi-cli のインストールから Docker 環境での活用、エラー対処までを網羅的に解説しました。公式ドキュメントと GitHub リポジトリを随時確認しながら、プロジェクトに最適な開発フローを構築してください。