Agent skill

uvicorn

ASGI server for Python web applications - Fast, production-ready server for async frameworks

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/bossjones/uvicorn

SKILL.md

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"}

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results