tessl/pypi-uvicorn

The lightning-fast ASGI server.

Overview

Eval results

Files

Command-Line Interface

Name: tessl/pypi-uvicorn
Author: tessl

Complete command-line interface for running uvicorn from the terminal.

Imports

from uvicorn.main import main

Command Syntax

uvicorn [OPTIONS] APP

Arguments

APP  ASGI application import string (e.g., "myapp:app")

The application can be specified as:

Module and attribute: myapp:app (imports app from myapp module)
Module and factory: myapp:create_app with --factory flag
Nested attributes: myapp.wsgi:application

CLI Function

def main() -> None:
    """
    Main CLI entry point decorated with Click.

    Parses command-line arguments and runs the ASGI server.
    All options are passed to the run() function.

    Exit codes:
    - 0: Normal exit
    - 3: Startup failure (STARTUP_FAILURE constant)
    """

Options

Network Binding

--host TEXT

Bind socket to this host. (default: 127.0.0.1)

--port INTEGER

Bind socket to this port. (default: 8000)

--uds TEXT

Bind to Unix domain socket at this path.

--fd INTEGER

Bind to socket from this file descriptor.

Development

--reload

Enable auto-reload on file changes. (default: disabled)

--reload-dir PATH

Set directories to watch for file changes. Can be specified multiple times. (default: current directory)

--reload-include TEXT

Set glob patterns to include for reload watching. Can be specified multiple times.

--reload-exclude TEXT

Set glob patterns to exclude from reload watching. Can be specified multiple times.

--reload-delay FLOAT

Delay in seconds between checking for file changes. (default: 0.25)

Workers

--workers INTEGER

Number of worker processes to run. (default: 1)

Event Loop

--loop [none|auto|asyncio|uvloop]

Event loop implementation. (default: auto)

auto: Automatically select uvloop if available, otherwise asyncio
asyncio: Use asyncio event loop
uvloop: Use uvloop (requires uvloop package)
none: No event loop configuration

HTTP Protocol

--http [auto|h11|httptools]

HTTP protocol implementation. (default: auto)

auto: Automatically select httptools if available, otherwise h11
h11: Use h11 pure-Python implementation
httptools: Use httptools (requires httptools package)

WebSocket

--ws [auto|none|websockets|websockets-sansio|wsproto]

WebSocket protocol implementation. (default: auto)

auto: Automatically select websockets if available
none: Disable WebSocket support
websockets: Use websockets library
websockets-sansio: Use websockets sans-IO implementation
wsproto: Use wsproto library

--ws-max-size INTEGER

Maximum WebSocket message size in bytes. (default: 16777216)

--ws-max-queue INTEGER

Maximum WebSocket message queue length. (default: 32)

--ws-ping-interval FLOAT

WebSocket ping interval in seconds. (default: 20.0)

--ws-ping-timeout FLOAT

WebSocket ping timeout in seconds. (default: 20.0)

--ws-per-message-deflate / --no-ws-per-message-deflate

Enable/disable WebSocket per-message deflate compression. (default: enabled)

Lifespan

--lifespan [auto|on|off]

Lifespan event handling mode. (default: auto)

auto: Enable lifespan if application supports it
on: Force lifespan events (error if not supported)
off: Disable lifespan events

Interface

--interface [auto|asgi3|asgi2|wsgi]

Application interface type. (default: auto)

auto: Automatically detect interface type
asgi3: ASGI3 interface
asgi2: ASGI2 interface (class-based)
wsgi: WSGI interface

Logging

--log-config PATH

Logging configuration file path. Supports .json, .yaml, and .ini formats.

--log-level [critical|error|warning|info|debug|trace]

Logging level. (default: info)

--access-log / --no-access-log

Enable/disable access logging. (default: enabled)

--use-colors / --no-use-colors

Enable/disable colored logging output. (default: auto-detect)

Headers

--proxy-headers / --no-proxy-headers

Enable/disable proxy header parsing (X-Forwarded-*). (default: enabled)

--server-header / --no-server-header

Enable/disable Server header in responses. (default: enabled)

--date-header / --no-date-header

Enable/disable Date header in responses. (default: enabled)

--forwarded-allow-ips TEXT

Comma-separated list of IPs to trust for proxy headers. (default: 127.0.0.1)

--header TEXT

Add custom default header in Name:Value format. Can be specified multiple times.

Application

--root-path TEXT

Set ASGI root_path for sub-mounted applications. (default: "")

--app-dir TEXT

Add directory to PYTHONPATH before importing application. (default: current directory)

--factory

Treat APP as a factory function that returns the application. (default: disabled)

Performance

--limit-concurrency INTEGER

Maximum number of concurrent connections. (default: unlimited)

--backlog INTEGER

Socket listen backlog size. (default: 2048)

--limit-max-requests INTEGER

Maximum requests before worker restart. (default: unlimited)

Timeouts

--timeout-keep-alive INTEGER

Keep-alive connection timeout in seconds. (default: 5)

--timeout-graceful-shutdown INTEGER

Graceful shutdown timeout in seconds. (default: unlimited)

--timeout-worker-healthcheck INTEGER

Worker health check timeout in seconds. (default: 5)

SSL/TLS

--ssl-keyfile TEXT

SSL private key file path.

--ssl-certfile TEXT

SSL certificate file path.

--ssl-keyfile-password TEXT

Password for encrypted SSL private key.

--ssl-version INTEGER

SSL protocol version. (default: ssl.PROTOCOL_TLS_SERVER)

--ssl-cert-reqs INTEGER

SSL certificate requirements. (default: ssl.CERT_NONE)

--ssl-ca-certs TEXT

CA certificates file path for client verification.

--ssl-ciphers TEXT

SSL cipher configuration. (default: "TLSv1")

Protocol-Specific

--h11-max-incomplete-event-size INTEGER

Maximum buffer size for h11 incomplete events in bytes.

--env-file PATH

Environment file (.env) to load before starting.

Information

--version

Display uvicorn version and exit.

--help

Display help message and exit.

Usage Examples

Basic Usage

# Run application from myapp module
uvicorn myapp:app

# Specify host and port
uvicorn myapp:app --host 0.0.0.0 --port 8000

# Run on all interfaces
uvicorn myapp:app --host 0.0.0.0

Development Mode

# Enable auto-reload
uvicorn myapp:app --reload

# Watch specific directories
uvicorn myapp:app --reload --reload-dir ./src --reload-dir ./lib

# Watch specific file patterns
uvicorn myapp:app --reload \
  --reload-include "*.py" \
  --reload-include "*.yaml" \
  --reload-exclude "*.pyc"

# Enable debug logging
uvicorn myapp:app --reload --log-level debug

# Enable trace logging
uvicorn myapp:app --reload --log-level trace

Production Mode

# Run with multiple workers
uvicorn myapp:app --host 0.0.0.0 --port 8000 --workers 4

# Production configuration
uvicorn myapp:app \
  --host 0.0.0.0 \
  --port 8000 \
  --workers 4 \
  --limit-concurrency 1000 \
  --limit-max-requests 10000 \
  --timeout-keep-alive 5 \
  --timeout-graceful-shutdown 30 \
  --access-log

# Disable access logs for performance
uvicorn myapp:app --workers 4 --no-access-log

SSL/TLS

# Enable HTTPS
uvicorn myapp:app \
  --host 0.0.0.0 \
  --port 443 \
  --ssl-keyfile /path/to/key.pem \
  --ssl-certfile /path/to/cert.pem

# HTTPS with client verification
uvicorn myapp:app \
  --ssl-keyfile /path/to/key.pem \
  --ssl-certfile /path/to/cert.pem \
  --ssl-ca-certs /path/to/ca.pem \
  --ssl-cert-reqs 2

Unix Domain Socket

# Bind to Unix socket
uvicorn myapp:app --uds /tmp/uvicorn.sock

# Run behind Nginx with Unix socket
uvicorn myapp:app --uds /var/run/uvicorn.sock --workers 4

Protocol Selection

# Use specific HTTP protocol
uvicorn myapp:app --http h11
uvicorn myapp:app --http httptools

# Use specific WebSocket protocol
uvicorn myapp:app --ws websockets
uvicorn myapp:app --ws wsproto

# Disable WebSocket support
uvicorn myapp:app --ws none

# Use specific event loop
uvicorn myapp:app --loop uvloop

Custom Headers

# Add custom default headers
uvicorn myapp:app \
  --header "X-API-Version:1.0" \
  --header "X-Server:MyAPI"

# Disable standard headers
uvicorn myapp:app --no-server-header --no-date-header

Proxy Configuration

# Trust proxy headers from localhost
uvicorn myapp:app --proxy-headers --forwarded-allow-ips "127.0.0.1"

# Trust multiple proxy IPs
uvicorn myapp:app --proxy-headers \
  --forwarded-allow-ips "127.0.0.1,10.0.0.1,192.168.1.1"

# Trust proxy network
uvicorn myapp:app --proxy-headers \
  --forwarded-allow-ips "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16"

# Disable proxy headers
uvicorn myapp:app --no-proxy-headers

Application Mounting

# Mount application at subpath
uvicorn myapp:app --root-path /api/v1

# Add custom module directory
uvicorn myapp:app --app-dir /path/to/app

# Use factory function
uvicorn myapp:create_app --factory

Logging Configuration

# Use custom logging config
uvicorn myapp:app --log-config logging.yaml

# JSON logging config
uvicorn myapp:app --log-config logging.json

# INI logging config
uvicorn myapp:app --log-config logging.ini

# Set log level
uvicorn myapp:app --log-level warning

Environment Configuration

# Load environment file
uvicorn myapp:app --env-file .env

# Load production environment
uvicorn myapp:app --env-file .env.production

WebSocket Configuration

# Configure WebSocket limits
uvicorn myapp:app \
  --ws-max-size 33554432 \
  --ws-max-queue 64 \
  --ws-ping-interval 30.0 \
  --ws-ping-timeout 30.0

# Disable WebSocket compression
uvicorn myapp:app --no-ws-per-message-deflate

Interface Selection

# Run ASGI2 application
uvicorn myapp:App --interface asgi2

# Run WSGI application (e.g., Flask)
uvicorn myapp:app --interface wsgi

# Auto-detect interface
uvicorn myapp:app --interface auto

Performance Tuning

# High-performance configuration
uvicorn myapp:app \
  --host 0.0.0.0 \
  --port 8000 \
  --workers 8 \
  --http httptools \
  --loop uvloop \
  --limit-concurrency 2000 \
  --backlog 4096 \
  --no-access-log

# Connection limiting
uvicorn myapp:app --limit-concurrency 500

# Request limiting
uvicorn myapp:app --limit-max-requests 50000

Timeouts

# Configure timeouts
uvicorn myapp:app \
  --timeout-keep-alive 10 \
  --timeout-graceful-shutdown 60 \
  --timeout-worker-healthcheck 10

Python Module Execution

# Run uvicorn as module
python -m uvicorn myapp:app

# With options
python -m uvicorn myapp:app --host 0.0.0.0 --port 8000 --reload

Lifespan Control

# Force lifespan events
uvicorn myapp:app --lifespan on

# Disable lifespan events
uvicorn myapp:app --lifespan off

# Auto-detect lifespan support
uvicorn myapp:app --lifespan auto

Complete Production Example

uvicorn myapp:app \
  --host 0.0.0.0 \
  --port 8000 \
  --workers 4 \
  --loop uvloop \
  --http httptools \
  --ws websockets \
  --proxy-headers \
  --forwarded-allow-ips "10.0.0.0/8" \
  --limit-concurrency 1000 \
  --backlog 2048 \
  --limit-max-requests 100000 \
  --timeout-keep-alive 5 \
  --timeout-graceful-shutdown 30 \
  --timeout-worker-healthcheck 10 \
  --access-log \
  --log-level info \
  --no-use-colors

Complete Development Example

uvicorn myapp:app \
  --host 127.0.0.1 \
  --port 8000 \
  --reload \
  --reload-dir ./src \
  --reload-include "*.py" \
  --reload-include "*.yaml" \
  --reload-exclude "*.pyc" \
  --reload-exclude "__pycache__/*" \
  --log-level debug \
  --use-colors \
  --access-log

Environment Variables

Uvicorn CLI also respects environment variables for configuration when using an env-file:

# .env file
HOST=0.0.0.0
PORT=8000
WORKERS=4
LOG_LEVEL=info
RELOAD=false

# Load from env file
uvicorn myapp:app --env-file .env

Exit Codes

0: Normal exit (server shutdown gracefully)
3: Startup failure (application failed to start)

Version Information

# Show version
uvicorn --version

# Output format:
# Running uvicorn 0.37.0 with CPython 3.11.0 on Linux

Help Information

# Show help
uvicorn --help

# Show detailed help for all options
uvicorn --help

Running with Gunicorn

Uvicorn can also be used as a Gunicorn worker (deprecated, use uvicorn-worker package instead):

gunicorn myapp:app -w 4 -k uvicorn.workers.UvicornWorker

Docker Usage

# Dockerfile
FROM python:3.11
WORKDIR /app
COPY . .
RUN pip install uvicorn[standard]
CMD ["uvicorn", "myapp:app", "--host", "0.0.0.0", "--port", "8000"]

# Build and run
docker build -t myapp .
docker run -p 8000:8000 myapp

Systemd Service

# /etc/systemd/system/uvicorn.service
[Unit]
Description=Uvicorn ASGI Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/myapp
ExecStart=/usr/local/bin/uvicorn myapp:app \
  --host 0.0.0.0 \
  --port 8000 \
  --workers 4
Restart=always

[Install]
WantedBy=multi-user.target

# Enable and start service
sudo systemctl enable uvicorn
sudo systemctl start uvicorn

Install with Tessl CLI

npx tessl i tessl/pypi-uvicorn

docs

tessl/pypi-uvicorn

cli.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Command-Line Interface

Imports

Command Syntax

Arguments

CLI Function

Options

Network Binding

Development

Workers

Event Loop

HTTP Protocol

WebSocket

Lifespan

Interface

Logging

Headers

Application

Performance

Timeouts

SSL/TLS

Protocol-Specific

Information

Usage Examples

Basic Usage

Development Mode

Production Mode

SSL/TLS

Unix Domain Socket

Protocol Selection

Custom Headers

Proxy Configuration

Application Mounting

Logging Configuration

Environment Configuration

WebSocket Configuration

Interface Selection

Performance Tuning

Timeouts

Python Module Execution

Lifespan Control

Complete Production Example

Complete Development Example

Environment Variables

Exit Codes

Version Information

Help Information

Running with Gunicorn

Docker Usage

Systemd Service

cli.mddocs/