CheatUvicorn ASGI web server
Light · Postcard
102 × 152 mm · PDF
Dark · Postcard
102 × 152 mm · PDF
Ink saver · Postcard
102 × 152 mm · PDF
Light · A4 landscape
297 × 210 mm · PDF
Dark · A4 landscape
297 × 210 mm · PDF
Ink saver · A4 landscape
297 × 210 mm · PDF
Light · A3 landscape
420 × 297 mm · PDF
Dark · A3 landscape
420 × 297 mm · PDF
Ink saver · A3 landscape
420 × 297 mm · PDF
Start here
uvicorn main:app
Serve an ASGI app
uvicorn main:app --reload
Restart on code change
uvicorn main:app --host 0.0.0.0
Listen on all interfaces
uvicorn main:app --port 8080
Pick the port
uvicorn main:app --workers 4
Four worker processes
uvicorn --factory main:create_app
Call an app factory
uvicorn main:app --log-level debug
More logging
uvicorn main:app --proxy-headers
Trust X-Forwarded-*
Concepts
- Client browser
- nginx TLS, static
- Uvicorn HTTP and ASGI
- Your app FastAPI etc.
Run
uvicorn <module>:<app>
Serve an ASGI app
uvicorn --factory <module>:<func>
Treat app as a factory
The function takes no arguments and returns the app.
uvicorn <module>:<app> --reload
Auto-restart on file change
Development only.
uvicorn <module>:<app> --workers
<n>
Run n worker processes
Defaults to $WEB_CONCURRENCY, else 1.
uvicorn --app-dir <dir>
<module>:<app>
Look for the app in a directory
uvicorn --env-file <file>
<module>:<app>
Load environment from a file
uvicorn --interface wsgi <module>:<app>
Serve a WSGI app
uvicorn --lifespan <auto|on|off>
Control startup/shutdown events
uvicorn --version
Print the version
uvicorn --helpList all options
python -m uvicorn <module>:<app>
Run via the interpreter
Uses the interpreter's environment, handy in venvs.
Binding
--host <addr>
Bind address (default 127.0.0.1)
--port <n>
Bind port (default 8000)
0 picks a free port.
--uds <path>
Bind a Unix socket
--fd <n>Use an inherited socket descriptor
For supervisors that hand over the socket.
--backlog <n>
Connection backlog size
--root-path <prefix>
App mounted below a URL path
| Goal | Flags |
|---|---|
| Local only | (default) |
| Container / LAN | --host 0.0.0.0 |
| Behind nginx | --uds /run/app.sock |
| Any free port | --port 0 |
Reload
--reloadWatch files and restart
--reload-dir <dir>
Watch this directory only
Repeatable. Stops it scanning venvs and node_modules.
--reload-include <glob>
Also watch matching files
Only has an effect when watchfiles is installed.
--reload-exclude <glob>
Ignore matching files
Only has an effect when watchfiles is installed.
--reload-delay <sec>
Pause between change checks
Workers and limits
--workers <n>
Number of worker processes
--limit-concurrency <n>
Answer 503 above n connections
--limit-max-requests <n>
Restart a process after n requests
--limit-max-requests-jitter <n>
Stagger those restarts
--timeout-keep-alive <sec>
Idle keep-alive timeout (default 5)
Keep it above the proxy's upstream keep-alive time.
--timeout-graceful-shutdown <sec>
Max wait on shutdown
kill -HUP <pid>
Gracefully restart workers
Works with --workers, not on Windows.
kill -TTIN <pid> / kill -TTOU <pid>
Add / remove one worker
Protocols
--http <impl>
h11 or httptools
--loop <impl>
asyncio or uvloop
--ws <lib>
websockets, websockets-sansio, wsproto
--ws-max-size <bytes>
Largest WebSocket message
--ws-ping-interval <sec>
WebSocket ping interval
--ws-ping-timeout <sec>
WebSocket ping timeout
--header <Name:Value>
Add a default response header
--no-server-header
Drop the Server header
--no-date-header
Drop the Date header
Logging
--log-level <level>
critical, error, warning, info, debug, trace
--no-access-logSilence request lines
--access-logEnable request lines (default)
--use-colors / --no-use-colors
Force or disable coloured logs
--log-config <file>
Logging config (.ini, .json, .yaml)
# logging.json: standard dictConfig layoutuvicorn main:app --log-config logging.jsonHTTPS and proxies
--ssl-keyfile <key> --ssl-certfile <crt>
Serve HTTPS directly
--ssl-keyfile-password <pw>
Password for the key
--ssl-ca-certs <file>
CA bundle for client certs
--ssl-cert-reqs <n>
Require a client certificate
Value from Python's ssl module (0 none, 2 required).
--proxy-headersRead X-Forwarded-For and -Proto
On by default; only trusted IPs are honoured.
--no-proxy-headers
Ignore forwarded headers
--forwarded-allow-ips <ips>
Trusted proxy IPs or sockets
Default 127.0.0.1,::1 (or $FORWARDED_ALLOW_IPS). '*'
trusts everyone: only if your proxy strips client-sent
headers.
Gunicorn and code
pip install uvicorn-workergunicorn main:app -w 4 -k uvicorn_worker.UvicornWorkerimport uvicornif __name__ == "__main__": uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)config = uvicorn.Config("main:app", port=8000)server = uvicorn.Server(config)await server.serve() # inside a running event loopRecipes
uvicorn main:app --reload --reload-dir src \ --log-level debuguvicorn main:app --host 0.0.0.0 --port 8000 \ --proxy-headers --forwarded-allow-ips '*' \ --no-access-loguvicorn main:app --uds /run/app.sock --workers 4 \ --proxy-headers# nginx: proxy_pass http://unix:/run/app.sock;mkcert localhostuvicorn main:app --ssl-keyfile localhost-key.pem \ --ssl-certfile localhost.pem
