uvicorn

Uvicorn スキルガイド

Uvicorn は、uvloop と httptools を使用した超高速の ASGI サーバー実装です。最新の Python 非同期 Web フレームワークで広く使われているサーバーです。

クイックスタート

基本的な使い方

# Run ASGI app
uvicorn main:app

# With host/port
uvicorn main:app --host 0.0.0.0 --port 8000

# Development with auto-reload
uvicorn main:app --reload

よくあるパターン

1. シンプルな ASGI アプリケーション

# main.py
async def app(scope, receive, send):
    assert scope['type'] == 'http'

    await send({
        'type': 'http.response.start',
        'status': 200,
        'headers': [(b'content-type', b'text/plain')],
    })
    await send({
        'type': 'http.response.body',
        'body': b'Hello, World!',
    })

2. FastAPI アプリケーション

# main.py
from fastapi import FastAPI

app = FastAPI()

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

uvicorn main:app --reload

3. アプリケーションファクトリーパターン

# main.py
from fastapi import FastAPI

def create_app():
    app = FastAPI()
    # Configure app
    return app

app = create_app()

uvicorn --factory main:create_app

4. プログラムによるサーバー制御

import uvicorn

# Simple run
if __name__ == "__main__":
    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

import asyncio
import uvicorn

async def main():
    config = uvicorn.Config("main:app", port=5000, log_level="info")
    server = uvicorn.Server(config)
    await server.serve()

if __name__ == "__main__":
    asyncio.run(main())

5. 環境変数による設定

export UVICORN_HOST="0.0.0.0"
export UVICORN_PORT="8000"
export UVICORN_RELOAD="true"
uvicorn main:app

本番環境へのデプロイ

マルチプロセスワーカー

# Use multiple worker processes
uvicorn main:app --workers 4

# Note: Can't use --reload with --workers

Gunicorn + Uvicorn

# Install gunicorn
pip install gunicorn

# Run with Gunicorn process manager
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

HTTPS/SSL

uvicorn main:app --ssl-keyfile=./key.pem --ssl-certfile=./cert.pem

Unix ソケット

uvicorn main:app --uds /tmp/uvicorn.sock

設定オプション

よく使う CLI フラグ

uvicorn main:app \
  --host 0.0.0.0 \
  --port 8000 \
  --reload \
  --reload-dir ./app \
  --log-level info \
  --access-log \
  --workers 4

主な設定

• --host：バインドするホスト（デフォルト：127.0.0.1）
• --port：バインドするポート（デフォルト：8000）
• --reload：開発用の自動リロードを有効にします
• --workers：ワーカープロセスの数
• --log-level：ログレベル（critical、error、warning、info、debug）
• --access-log：アクセスログを有効にします
• --factory：アプリをアプリケーションファクトリーとして扱います

Docker との連携

Dockerfile

FROM python:3.12-slim
WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy application
COPY . .

# Run with uvicorn
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

ホットリロード対応の Docker Compose

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - UVICORN_RELOAD=true
    volumes:
      - .:/app
    command: uvicorn main:app --host 0.0.0.0 --port 8000 --reload

トラブルシューティング

よくある問題

1. ポートがすでに使用されています：ポートを変更するか、既存のプロセスを終了してください
2. モジュールが見つかりません：PYTHONPATH を確認するか、--app-dir を使用してください
3. リロードが機能しません：--reload-dir で正しいディレクトリを監視していることを確認してください
4. ワーカー数：本番環境では --workers を使用し、--reload との併用は避けてください

デバッグモード

uvicorn main:app --reload --log-level debug

ヘルスチェック

@app.get("/health")
async def health():
    return {"status": "healthy"}