インストールと環境構築 — UV高速パッケージマネージャー
良い開発環境は, 設備の整ったキッチンのようなもの - 食材 (依存関係)は数秒で手に入り, コンロ (サーバー)はワンクリックで点火し, レシピ (プロジェクト構造)は整理整頓されています。
1. 学ぶ内容
- UVのインストールとコアコマンド:
uv init,uv add,uv runのワークフロー - PriceTrackerプロジェクトスケルトンの作成:ディレクトリ構造と命名規則
- Uvicorn開発サーバーの設定:
--reload,--host,--port,--workers .env環境変数管理とpython-dotenvとの連携uv run uvicornを使ってワンクリックで開発サービスを起動
2. Aliceの実際のストーリー
(1) 悩み:pipで依存関係をインストールするのが遅すぎる
Aliceはpipを使ってFastAPIプロジェクトの依存関係をインストールしていましたが, 完了までに3分かかりました。さらに悪いことに, チームのBobはPython 3.11を使っていましたが, Aliceは3.12を使っており - バージョンの不一致により仮想環境で頻繁に競合が発生しました。pip install -r requirements.txtを実行するたびに, ロックファイルのバージョン競合で失敗するかどうかが宝くじのようなものです。
(2) UVによる解決策
UVはAstralチームがRustで書いたPythonパッケージマネージャーです。pipより10〜100倍高速に依存関係をインストールし, 内蔵の仮想環境管理とPythonバージョン切り替え機能を備え, コマンド1つでプロジェクトを初期化できます。
BASH
# プロジェクトの初期化とFastAPIの追加を一括で
uv init pricetracker
cd pricetracker
uv add fastapi uvicorn
uv run uvicorn app.main:app --reload
(3) 成果
Aliceの依存関係インストール時間は3分から3秒に短縮されました。BobとAliceの環境は同一 (uv.lockでバージョン固定)となり, CI/CDのビルド時間も80%削減されました。
3. UVパッケージマネージャーの基礎
(1) UVコアコマンドクイックリファレンス
| コマンド | 機能 | pip相当 |
|---|---|---|
uv init |
プロジェクトの初期化 | 手動でvenv + requirements.txtを作成 |
uv add <pkg> |
pyproject.tomlに依存関係を追加 | pip install + 手動でrequirements.txtを更新 |
uv remove <pkg> |
依存関係の削除 | pip uninstall + 手動更新 |
uv run <cmd> |
仮想環境内でコマンドを実行 | source venv/bin/activate && cmd |
uv sync |
全依存関係の同期 | pip install -r requirements.txt |
uv lock |
依存関係バージョンの固定 | pip freeze > requirements.txt |
uv python install 3.12 |
Pythonのインストール | pyenv install 3.12 |
(1) ▶ サンプル:UVプロジェクトの初期化
BASH
# プロジェクトディレクトリの作成
uv init pricetracker
cd pricetracker
# これにより以下が作成されます:
# pricetracker/
# pyproject.toml
# .python-version
# hello.py
# .venv/ (自動作成される仮想環境)
出力:
TEXT
Initialized project pricetracker
(2) ▶ サンプル:FastAPI依存関係の追加
BASH
# FastAPIとUvicornの追加
uv add fastapi uvicorn[standard]
# pyproject.tomlの確認
cat pyproject.toml
出力 (pyproject.tomlの抜粋):
TEXT
[project]
name = "pricetracker"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
"fastapi>=0.115.0",
"uvicorn[standard]>=0.30.0",
]
(2) UV, pip, Poetryの比較
| 次元 | UV | pip | Poetry |
|---|---|---|---|
| インストール速度 | 10〜100倍高速 | ベンチマーク | 2〜5倍高速 |
| ロックファイル | uv.lock |
なし | poetry.lock |
| 仮想環境 | 自動管理 | 手動venv |
自動管理 |
| Pythonバージョン管理 | 内蔵 | なし | pyenvが必要 |
| 設定ファイル | pyproject.toml |
requirements.txt |
pyproject.toml |
| Rustコア | あり | なし | なし |
4. PriceTrackerプロジェクトスケルトン
(1) ディレクトリ構造の設計
graph TD
Root[pricetracker/] --> App[app/]
App --> Main[__init__.py]
App --> MainPy[main.py]
App --> Api[api/]
Api --> Routes[routes/]
Routes --> Products[products.py]
Routes --> Prices[prices.py]
Routes --> Auth[auth.py]
App --> Models[models/]
App --> Schemas[schemas/]
App --> Services[services/]
App --> Core[core/]
Core --> Config[config.py]
Core --> Security[security.py]
App --> Db[db.py]
Root --> Tests[tests/]
Root --> Alembic[alembic/]
Root --> Docker[docker/]
Root --> Env[.env]
Root --> Pyproject[pyproject.toml]
| ディレクトリ | 責務 | 説明 |
|---|---|---|
app/ |
メインアプリパッケージ | すべてのビジネスコード |
app/api/routes/ |
ルーティングモジュール | 機能別にエンドポイントを分割 |
app/models/ |
SQLAlchemyモデル | データベーステーブルマッピング |
app/schemas/ |
Pydanticモデル | リクエスト/レスポンスバリデーション |
app/services/ |
ビジネスロジック | ストレージ層とサービス層 |
app/core/ |
コア設定 | 設定, セキュリティ, 依存関係 |
tests/ |
テスト | pytestテストスイート |
alembic/ |
データベースマイグレーション | Alembicマイグレーションスクリプト |
docker/ |
コンテナ設定 | Dockerfile + Compose |
(1) ▶ サンプル:プロジェクトスケルトンの作成
BASH
# 全ディレクトリの作成
mkdir -p app/api/routes app/models app/schemas app/services app/core
mkdir -p tests alembic docker
# __init__.pyファイルの作成
touch app/__init__.py app/api/__init__.py app/api/routes/__init__.py
touch app/models/__init__.py app/schemas/__init__.py
touch app/services/__init__.py app/core/__init__.py
touch tests/__init__.py
出力:
TEXT
CONTAINER ID IMAGE STATUS
abc123 latest Up 2 hours
(2) ▶ サンプル:最小のFastAPIアプリケーション app/main.py
PYTHON
from fastapi import FastAPI
app = FastAPI(
title="PriceTracker API",
description="eコマース向けSaaS価格追跡サービス",
version="0.1.0",
)
@app.get("/health")
async def health_check():
return {"status": "healthy", "service": "pricetracker"}
出力:
TEXT
# 関数定義成功
5. Uvicorn開発サーバー
(1) Uvicornの主要パラメータ
| パラメータ | デフォルト値 | 説明 |
|---|---|---|
--host |
127.0.0.1 |
リスニングアドレス;0.0.0.0で外部アクセスを許可 |
--port |
8000 |
リスニングポート |
--reload |
False |
ファイル変更時に自動再起動 (開発用のみ) |
--reload-dir |
. |
監視ディレクトリ;複数指定可能 |
--workers |
1 |
ワーカープロセス数 (本番用;--reloadと競合) |
--log-level |
info |
ログレベル |
(1) ▶ サンプル:開発モードでの起動
BASH
# ホットリロードで起動 - コード変更で自動再起動
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
出力:
TEXT
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO: Started reloader process
INFO: Started server process
INFO: Waiting for application startup.
INFO: Application startup complete.
(2) ▶ サンプル:本番モードでの起動
BASH
# 本番:複数ワーカー, リロードなし
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
出力:
TEXT
# コマンド実行成功
(2) 開発環境と本番環境のUvicorn設定の比較
| 設定 | 開発環境 | 本番環境 |
|---|---|---|
--reload |
オン | オフ |
--workers |
1 | CPUコア数 x 2 + 1 |
--host |
127.0.0.1 | 0.0.0.0 |
--log-level |
debug | info/warning |
| フロントプロキシ | なし | Nginx/Traefik |
6. 環境変数管理
(1) .envファイルとpython-dotenv
環境変数は12-Factor Appの中核原則です。機密設定 (データベースパスワードやJWT鍵など)は絶対にハードコードしてはいけません。
(1) ▶ サンプル:.envファイルの作成
INI
# .env - このファイルをgitにコミットしてはいけません!
APP_NAME=PriceTracker
DEBUG=true
DATABASE_URL=postgresql+asyncpg://pricetracker:secret@localhost:5432/pricetracker
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=your-super-secret-key-change-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
出力:
TEXT
// 実行成功
(2) ▶ サンプル:Pydantic Settingsで環境変数を読み取る
PYTHON
# app/core/config.py
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
app_name: str = "PriceTracker"
debug: bool = False
database_url: str = "postgresql+asyncpg://localhost/pricetracker"
redis_url: str = "redis://localhost:6379/0"
secret_key: str = "change-me-in-production"
algorithm: str = "HS256"
access_token_expire_minutes: int = 30
model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
settings = Settings()
出力:
TEXT
# 実行成功
(3) ▶ サンプル:FastAPIで設定を使用する
PYTHON
# app/main.py
from fastapi import FastAPI
from app.core.config import settings
app = FastAPI(
title=settings.app_name,
debug=settings.debug,
)
@app.get("/info")
async def app_info():
return {
"app": settings.app_name,
"debug": settings.debug,
"database": settings.database_url.split("@")[-1], # 認証情報を隠す
}
出力:
TEXT
# 関数定義成功
(2) .gitignoreの必須項目
BASH
# .gitignoreに追加
.env
.env.local
.env.production
.venv/
__pycache__/
*.pyc
| ファイル | コミット | 理由 |
|---|---|---|
.env |
しない | 機密情報を含む |
.env.example |
する | チーム参照テンプレート |
uv.lock |
する | 依存関係バージョンの固定 |
pyproject.toml |
する | プロジェクト設定 |
7. 総合サンプル
UVパッケージ管理, Pydantic Settings設定, Uvicorn起動を組み合わせ, プロジェクト初期化からサービスデプロイまでの完全なプロセスをデモします。
PYTHON
# pyproject.toml依存関係:fastapi, uvicorn, pydantic-settings
from fastapi import FastAPI
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
app_name: str = "PriceTracker"
debug: bool = False
database_url: str = "postgresql+asyncpg://user:pass@localhost/pricetracker"
model_config = {"env_file": ".env"}
settings = Settings()
app = FastAPI(title=settings.app_name, debug=settings.debug)
@app.get("/health")
async def health():
return {"status": "ok", "app": settings.app_name}
@app.get("/info")
async def info():
return {"app": settings.app_name, "debug": settings.debug}
# 起動:uv run uvicorn app.main:app --reload
出力:
TEXT
GET /health → {"status":"ok","app":"PriceTracker"}
GET /info → {"app":"PriceTracker","debug":false}
❓ よくある質問
Q UVとpipは併用できますか?
A お勧めしません。UVは
uv.lockと仮想環境を管理しています。pipを併用すると依存関係の競合が発生する可能性があります。uv add/uv runのワークフローに統一してください。Q なぜGunicornではなくUvicornを使うのですか?
A Uvicornは非同期をサポートするASGIサーバーです。Gunicornは非同期をサポートしないWSGIサーバーです。本番環境では, Gunicorn + Uvicorn Workersのハイブリッドモードを使用できます。
Q --reloadと--workersは同時に使用できますか?
A いいえ。--reloadは単一プロセスのみサポートしています。本番環境では--workersでマルチプロセス運用を行い, --reloadは有効にしないでください。
Q .envファイルはどこに配置すべきですか?
A プロジェクトルートディレクトリに, pyproject.tomlと同じ階層に配置してください。必ず.gitignoreに追加し, チーム用の.env.exampleファイルを提供してください。
Q Pydantic Settingsとpython-dotenvはどちらが良いですか?
A Pydantic Settings (pydantic-settingsパッケージ)をお勧めします。型チェック, デフォルト値, ネスト設定をサポートしており, python-dotenvより安全で強力です。
Q UVのインストールに失敗した場合はどうすればよいですか?
A インターネット接続を確認し, システムがRustビルドツールチェーンをサポートしているか確認してください。Windowsユーザーは
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"でインストールできます。📖 まとめ
- UVはRustで書かれており, pipより10〜100倍高速に依存関係をインストールし, 内蔵の仮想環境とPythonバージョン管理を備えています。
- PriceTrackerプロジェクトは5層のレイヤードアーキテクチャを採用:api/routes, models, schemas, services, core
- Uvicornは開発時に
--reloadでホットリロード, 本番時に--workersでマルチプロセス運用を行います .env+ Pydantic Settings:環境変数を管理し, 機密設定はハードコードしないuv run uvicorn app.main:app --reloadでワンコマンドで開発環境を起動
📝 練習問題
- 基本問題 (難易度 ⭐):
uv initでプロジェクトを作成し, FastAPIとUvicornの依存関係を追加し, 最初の「Hello World」エンドポイントを実行してください。ヒント:uv add fastapi uvicorn - 応用問題 (難易度 ⭐⭐):PriceTrackerプロジェクトのディレクトリ構造を作成し,
/healthエンドポイントを含むapp/main.pyを書き,uv run uvicornで起動して確認してください。ヒント:本記事のディレクトリ構造図を参照してください。 - チャレンジ問題 (難易度 ⭐⭐⭐):Pydantic Settingsを使って
.envファイルから読み取る設定クラスを作成し,DATABASE_URLとSECRET_KEYを読み込み,/infoエンドポイントでアプリケーション名を返してください (秘密は露出させない)。ヒント:pip install pydantic-settings, つまりuv add pydantic-settings



