uvicorn

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

# 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

# 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

# main.py
from fastapi import FastAPI

app = FastAPI()

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

uv run uvicorn main:app --reload

3. Application Factory Pattern

# main.py
from fastapi import FastAPI

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

app = create_app()

uv run uvicorn --factory main:create_app

4. Programmatic Server Control

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

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

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

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

Gunicorn + Uvicorn

# Install gunicorn
uv add gunicorn

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

HTTPS/SSL

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

Unix Socket

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

Configuration Options

Common CLI Flags