サイトアイコン IT & ライフハックブログ｜学びと実践のためのアイデア集

FastAPIをvenvで始める方法：環境構築からAPIの動作確認まで

greeden
green snake

Photo by Pixabay on Pexels.com

FastAPIを試したいものの、既存のPython環境にパッケージを混ぜたくない場合は、標準機能のvenvでプロジェクト専用の環境を作ると依存関係を分けて管理できます。

この記事では、venvの作成からFastAPIのインストール、最小構成のAPI起動、ブラウザとcurlによる動作確認までを順に進めます。

Pythonの基本的な文法を理解し、初めてWeb APIを動かす読者を想定しています。

最初に知っておきたい4つの用語

手順に入る前に、登場する用語の役割を分けておくと、エラーが起きた場所を判断しやすくなります。

手順1：Pythonの実行環境を確認する

ターミナルまたはコマンドプロンプトを開き、インストール済みのPythonを確認します。

macOSまたはLinux

python3 --version

Windows

py --version

バージョン番号が表示されなければ、コマンド名としてpythonも試してください。

Pythonが未導入の場合は、Python公式ダウンロードページから利用環境に合う配布物を入手します。

FastAPIが対応するPythonの範囲はリリースにより変わるため、固定された古いバージョンを選ばず、利用時点のFastAPI公式チュートリアルと照合してください。

手順2：プロジェクト用フォルダを作る

作業場所を決め、プロジェクト用のフォルダへ移動します。

mkdir fastapi-venv-project
cd fastapi-venv-project

以降のコマンドは、このフォルダ内で実行します。

手順3：venvで仮想環境を作る

Python公式のvenvドキュメントに沿って、.venvという名前の仮想環境を作成します。

macOSまたはLinux

python3 -m venv .venv

Windows

py -m venv .venv

.venvはフォルダ名であり、別の名前も使えます。

仮想環境は別の端末へコピーして使うものではないため、Gitを利用する場合は.gitignoreに.venv/を追加します。

手順4：仮想環境を有効化する

有効化すると、通常のpythonやpipが仮想環境内の実行ファイルを参照するようになります。

シェル別のvenv有効化コマンド
環境 コマンド
macOSまたはLinuxのbash、zsh source .venv/bin/activate
Windows PowerShell .\.venv\Scripts\Activate.ps1
Windows コマンドプロンプト .venv\Scripts\activate.bat

有効化後は、次のコマンドで実際に使われているPythonの場所を確認できます。

python -c "import sys; print(sys.executable)"

表示されたパスに.venvが含まれていれば、作成した仮想環境を使えています。

作業を終えるときは、次のコマンドで元の環境へ戻ります。

deactivate

手順5：FastAPIとUvicornをインストールする

仮想環境を有効にしたまま、pipを更新してFastAPIをインストールします。

python -m pip install --upgrade pip
python -m pip install "fastapi[standard]"

python -m pipと書くことで、直前に確認したPythonに対応するpipを実行できます。

fastapi[standard]は、FastAPI本体に加えてUvicornなど標準的な追加依存関係を導入する、FastAPI公式が案内しているインストール方法です。

インストール先を確認するには、次のコマンドを使います。

python -m pip show fastapi

手順6：最小構成のAPIを作る

プロジェクト直下にmain.pyを作り、次のコードを保存します。

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
async def read_root():
    return {"message": "Hello, World!"}

app = FastAPI()はアプリケーション本体を作る行です。

@app.get("/")は、ルートパス/へのGETリクエストをread_root()で処理するよう登録します。

関数が返す辞書はJSONレスポンスに変換されるため、ブラウザやほかのプログラムから内容を受け取れます。

手順7：開発用サーバーを起動する

main.pyがあるフォルダで、次のコマンドを実行します。

python -m uvicorn main:app --reload

終了するときは、起動したターミナルでCtrl+Cを押します。

手順8：レスポンスとAPIドキュメントを確認する

サーバーを起動したまま、ブラウザでローカルのルートAPIを開きます。

次のJSONが表示されれば、FastAPIがリクエストを受け取り、処理結果を返せています。

{"message":"Hello, World!"}

ターミナルから確認する場合は、次のようにcurlを実行します。

curl http://127.0.0.1:8000/

FastAPIが生成するドキュメント画面も確認できます。

よくあるエラーの切り分け方

エラーメッセージだけで対処を決めず、Python、仮想環境、パッケージ、起動位置の順に確認すると原因を狭めやすくなります。

FastAPIの環境構築で起きやすい問題
症状 確認と対処
python3またはpyが見つからない python --versionも試します。どのコマンドでもバージョンが表示されなければ、Pythonのインストール状況と実行パスを確認します。
PowerShellでActivate.ps1を実行できない 組織や端末の実行ポリシーを確認します。ポリシーを不用意に変更せず、コマンドプロンプトのactivate.batを使うか、.\.venv\Scripts\python.exeを直接指定できます。
ModuleNotFoundError: No module named 'fastapi' python -c "import sys; print(sys.executable)"とpython -m pip show fastapiを実行し、同じ仮想環境にFastAPIが入っているか確認します。
Error loading ASGI app main.pyがあるフォルダで実行しているか、ファイル名がmain.py、オブジェクト名がappになっているか確認します。
8000番ポートが使用中と表示される python -m uvicorn main:app --reload --port 8001で別のポートを指定し、URLもhttp://127.0.0.1:8001/へ変更します。
/docsを開けない サーバーを起動したターミナルが動作中か、起動ログに表示されたURLとポートが一致しているか確認します。

最小APIの次に進む順序

最初のレスポンスを確認できたら、機能を増やす前に入力と出力の型を決めます。

  1. Pythonの型ヒントとPydanticによる入力検証を学ぶ。
  2. パスパラメータとクエリパラメータを追加し、複数のルートを作る。
  3. 1ファイルのFastAPIを保守しやすい構成へ分ける方法を確認する。
  4. データベース、認証、テストを追加し、FastAPIを本番運用へ進めるチェック項目を確認する。

FastAPIを動かすまでの確認事項

ここまで確認できれば、Pythonのグローバル環境とプロジェクトの依存関係を分けた状態で、FastAPIの学習を続けられます。

この記事に関連する株式会社greedenの取り組み

FastAPIで小さなAPIを動かした後は、要件整理と運用設計が次の課題です。株式会社greedenは、FastAPIを含むWebシステム開発を、要件定義から実装、テスト、リリース後の保守改善まで支援しています。

モバイルバージョンを終了