RUNNING(1)

📦
version 0.38.0 · 4 versions
, in ubuntu resolute, ubuntu stonking

🌸 RUNNING(1) — the Running page, bestie edition 🌸

okay so. this is the manual for Running — an ASGI server implementation, using uvloop and httptools. it lives in section 1 of the manual (User Commands, iykyk) and honestly? she's iconic. let's get into it. 💅

✨ NAME ✨

Running — ASGI server implementation, using uvloop and httptools. that's the whole vibe. that's her. 🦋

✨ SYNOPSIS ✨

uvicorn [OPTIONS] APP

like. that's it. that's the whole spell. options go in, APP goes last, server goes brrr. ✨

✨ OPTIONS ✨

okay bestie, here's the full menu. every single one. no skips, no skimming, we're doing this properly. 🎀

🌐 where do we even listen

  • --host TEXT — bind the socket to this host. [default: 127.0.0.1]
  • --port INTEGER — bind the socket to this port. if it's 0, an available port gets picked for you, cute. [default: 8000]
  • --uds TEXT — bind to a UNIX domain socket instead.
  • --fd INTEGER — bind to the socket from this file descriptor. fancy.

🔄 auto-reload era (the "omg I saved the file" section)

  • --reload — enable auto-reload. the file-watcher fantasy. 🔥
  • --reload-dir PATH — set the reload directories explicitly instead of just using the current working directory.
  • --reload-include TEXT — set glob patterns to include while watching for files. includes *.py by default; these defaults can be overridden with --reload-exclude. heads up: this option has no effect unless watchfiles is installed.
  • --reload-exclude TEXT — set glob patterns to exclude while watching for files. includes .*, .py[cod], .sw.*, ~* by default; these defaults can be overridden with --reload-include. also: this option has no effect unless watchfiles is installed.
  • --reload-delay FLOAT — delay between the previous and next check if the application needs to be reloaded. defaults to 0.25s. [default: 0.25]

👯 workers & concurrency

  • --workers INTEGER — number of worker processes. defaults to the $WEB_CONCURRENCY environment variable if it's available, or 1. not valid with --reload, so pick a lane bestie.
  • --limit-concurrency INTEGER — maximum number of concurrent connections or tasks to allow before issuing HTTP 503 responses. (yes, the sad little 503. 🥲)
  • --backlog INTEGER — maximum number of connections to hold in the backlog.
  • --limit-max-requests INTEGER — maximum number of requests to service before terminating the process.

🧚 the implementations (aka choose your fighter)

  • --loop [auto|asyncio|uvloop] — event loop factory implementation. [default: auto]
  • --http [auto|h11|httptools] — HTTP protocol implementation. [default: auto]
  • --ws [auto|websockets|websockets-sansio|wsproto] — WebSocket protocol implementation. [default: auto]
  • --lifespan [auto|on|off] — lifespan implementation. [default: auto]
  • --interface [auto|asgi3|asgi2|wsgi] — select ASGI3, ASGI2, or WSGI as the application interface. [default: auto]

🕸️ websocket girlies, this one's for you

  • --ws-max-size INTEGER — WebSocket max size message in bytes. [default: 16777216]
  • --ws-max-queue INTEGER — the maximum length of the WebSocket message queue. [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 BOOLEAN — WebSocket per-message-deflate compression. [default: True]

⏱️ timeouts & graceful exits

  • --timeout-keep-alive INTEGER — close Keep-Alive connections if no new data is received within this timeout (in seconds). [default: 5]
  • --timeout-graceful-shutdown INTEGER — maximum number of seconds to wait for graceful shutdown.
  • --timeout-worker-healthcheck INTEGER — maximum number of seconds to wait for a worker to respond to a healthcheck. [default: 5]

📁 files, config & logs

  • --env-file PATH — environment configuration file.
  • --log-config PATH — logging configuration file. supported formats: .ini, .json, .yaml.
  • --log-level [critical|error|warning|info|debug|trace] — log level. [default: info]
  • --app-dir TEXT — look for APP in the specified directory, by adding this to the PYTHONPATH. defaults to the current working directory. [default: ""]

🔀 on/off toggles (both directions, always)

  • --access-log / --no-access-log — enable/disable the access log.
  • --use-colors / --no-use-colors — enable/disable colorized logging. (say yes. color is the moment. 🌈)
  • --proxy-headers / --no-proxy-headers — enable/disable X-Forwarded-Proto, X-Forwarded-For to populate url scheme and remote address info.
  • --server-header / --no-server-header — enable/disable the default Server header.
  • --date-header / --no-date-header — enable/disable the default Date header.

🫶 trusting proxies & mounting paths

  • --forwarded-allow-ips TEXT — comma separated list of IP Addresses, IP Networks, or literals (e.g. UNIX Socket path) to trust with proxy headers. defaults to the $FORWARDED_ALLOW_IPS environment variable if available, or '127.0.0.1'. the literal '*' means trust everything. everything. be careful with that one bestie.
  • --root-path TEXT — set the ASGI 'root_path' for applications submounted below a given URL path.

🔐 SSL / TLS section (the locked-down, mysterious era)

  • --ssl-keyfile TEXT — SSL key file
  • --ssl-certfile TEXT — SSL certificate file
  • --ssl-keyfile-password TEXT — SSL keyfile password
  • --ssl-version INTEGER — SSL version to use (see stdlib ssl module's) [default: 17]
  • --ssl-cert-reqs INTEGER — whether client certificate is required (see stdlib ssl module's) [default: 0]
  • --ssl-ca-certs TEXT — CA certificates file
  • --ssl-ciphers TEXT — ciphers to use (see stdlib ssl module's) [default: TLSv1]

✨ custom stuff & housekeeping

  • --header TEXT — specify custom default HTTP response headers as a Name:Value pair
  • --h11-max-incomplete-event-size INTEGER — for h11, the maximum number of bytes to buffer of an incomplete event.
  • --factory — treat APP as an application factory, i.e. a () -> <ASGI app> callable.
  • --version — display the uvicorn version and exit. (screenshot it. post it. 🫶)
  • --help — show this message and exit.

✨ SEE ALSO ✨

the full documentation for Running is maintained as a Texinfo manual. if the info and Running programs are properly installed at your site, this command

info Running

should give you access to the complete manual. go read her, she's thorough. 💜

and that's the whole page bestie!! slay, you read all of it, I'm so proud 🎀

okay so for the little sign-off — this whole thing is Running uvicorn 0.38.0 with C..., dated December 2025, and it's the RUNNING(1) page. no cap. 💖✨🦋

📦 where this page comes from