Uvicorn Skill Guide

Uvicorn is a lightning-fast ASGI server implementation, using uvloop and httptools. It's the go-to server for modern Python async web frameworks.

Quick Start

Basic Usage

bash
# Run ASGI app
uv run uvicorn main:app

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

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

Common Patterns

1. Simple ASGI Application

python
# 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 Application

python
# main.py
from fastapi import FastAPI

app = FastAPI()

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

bash
uv run uvicorn main:app --reload

3. Application Factory Pattern

python
# main.py
from fastapi import FastAPI

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

app = create_app()

bash
uv run uvicorn --factory main:create_app

4. Programmatic Server Control

python
import uvicorn

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

python
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. Configuration with Environment Variables

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

Production Deployment

Multi-Process Workers

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

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

Gunicorn + Uvicorn

bash
# Install gunicorn
uv add gunicorn

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

HTTPS/SSL

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

Unix Socket

bash
uv run uvicorn main:app --uds /tmp/uvicorn.sock

Configuration Options

Common CLI Flags

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

Key Settings

• --host: Bind host (default: 127.0.0.1)
• --port: Bind port (default: 8000)
• --reload: Enable auto-reload for development
• --workers: Number of worker processes
• --log-level: Logging level (critical, error, warning, info, debug)
• --access-log: Enable access logging
• --factory: Treat app as application factory

Docker Integration

Dockerfile

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 with Hot Reload

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

Troubleshooting

Common Issues

1. Port already in use: Change port or kill existing process
2. Module not found: Check PYTHONPATH or use --app-dir
3. Reload not working: Ensure watching correct directories with --reload-dir
4. Worker count: Use --workers for production, avoid with --reload

Debug Mode

bash
uv run uvicorn main:app --reload --log-level debug

Health Checks

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