Skip to content

# Welcome

An ASGI web server, for Python.

Documentation: https://uvicorn.dev

Source Code: https://www.github.com/Kludex/uvicorn

Uvicorn is an ASGI web server implementation for Python.

Until recently Python has lacked a minimal low-level server/application interface for async frameworks. The ASGI specification fills this gap, and means we're now able to start building a common set of tooling usable across all async frameworks.

Uvicorn currently supports HTTP/1.1 and WebSockets.

## Quickstart

Uvicorn is available on PyPI so installation is as simple as:

pip uv

    pip install uvicorn

    uv add uvicorn

See the installation documentation for more information.

Let's create a simple ASGI application to run with Uvicorn:

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'),
                (b'content-length', b'13'),
            ],
        })
        await send({
            'type': 'http.response.body',
            'body': b'Hello, world!',
        })

Then we can run it with Uvicorn:

    uvicorn main:app

## Usage

The uvicorn command line tool is the easiest way to run your application.

### Command line options

    Usage: python -m uvicorn [OPTIONS] APP

    Options:
      --host TEXT                     Bind socket to this host.  [default:
                                      127.0.0.1]
      --port INTEGER                  Bind socket to this port. If 0, an available
                                      port will be picked.  [default: 8000]
      --uds TEXT                      Bind to a UNIX domain socket.
      --fd INTEGER                    Bind to socket from this file descriptor.
      --reload                        Enable auto-reload.
      --reload-dir PATH               Set reload directories explicitly, instead
                                      of 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`. 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`. This
                                      option has no effect unless watchfiles is
                                      installed.
      --reload-delay FLOAT            Delay between previous and next check if
                                      application needs to be. Defaults to 0.25s.
                                      [default: 0.25]
      --workers INTEGER               Number of worker processes. Defaults to the
                                      $WEB_CONCURRENCY environment variable if
                                      available, or 1. Not valid with --reload.
      --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]
      --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]
      --lifespan [auto|on|off]        Lifespan implementation.  [default: auto]
      --interface [auto|asgi3|asgi2|wsgi]
                                      Select ASGI3, ASGI2, or WSGI as the
                                      application interface.  [default: auto]
      --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]
      --access-log / --no-access-log  Enable/Disable access log.
      --use-colors / --no-use-colors  Enable/Disable colorized logging.
      --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 default Server header.
      --date-header / --no-date-header
                                      Enable/Disable default Date header.
      --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.
      --root-path TEXT                Set the ASGI 'root_path' for applications
                                      submounted below a given URL path.
      --limit-concurrency INTEGER     Maximum number of concurrent connections or
                                      tasks to allow, before issuing HTTP 503
                                      responses.
      --backlog INTEGER               Maximum number of connections to hold in
                                      backlog
      --limit-max-requests INTEGER    Maximum number of requests to service before
                                      terminating the process.
      --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]
      --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]
      --header TEXT                   Specify custom default HTTP response headers
                                      as a Name:Value pair
      --version                       Display the uvicorn version and exit.
      --app-dir TEXT                  Look for APP in the specified directory, by
                                      adding this to the PYTHONPATH. Defaults to
                                      the current working directory.  [default:
                                      ""]
      --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.
      --help                          Show this message and exit.

For more information, see the settings documentation.

### Running programmatically

There are several ways to run uvicorn directly from your application.

#### `uvicorn.run`

If you're looking for a programmatic equivalent of the `uvicorn` command line interface, use `uvicorn.run()`:

main.py

    import uvicorn

    async def app(scope, receive, send):
        ...

    if __name__ == "__main__":
        uvicorn.run("main:app", port=5000, log_level="info")

#### `Config` and `Server` instances

For more control over configuration and server lifecycle, use `uvicorn.Config` and `uvicorn.Server`:

main.py

    import uvicorn

    async def app(scope, receive, send):
        ...

    if __name__ == "__main__":
        config = uvicorn.Config("main:app", port=5000, log_level="info")
        server = uvicorn.Server(config)
        server.run()

If you'd like to run Uvicorn from an already running async environment, use `uvicorn.Server.serve()` instead:

main.py

    import asyncio
    import uvicorn

    async def app(scope, receive, send):
        ...

    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())

### Running with Gunicorn

Warning

The `uvicorn.workers` module is deprecated and will be removed in a future release.

You should use the `uvicorn-worker` package instead.

    python -m pip install uvicorn-worker

Gunicorn is a mature, fully featured server and process manager.

Uvicorn includes a Gunicorn worker class allowing you to run ASGI applications, with all of Uvicorn's performance benefits, while also giving you Gunicorn's fully-featured process management.

This allows you to increase or decrease the number of worker processes on the fly, restart worker processes gracefully, or perform server upgrades without downtime.

For production deployments we recommend using gunicorn with the uvicorn worker class.

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

For a PyPy compatible configuration use `uvicorn.workers.UvicornH11Worker`.

For more information, see the deployment documentation.

### Application factories

The `--factory` flag allows loading the application from a factory function, rather than an application instance directly. The factory will be called with no arguments and should return an ASGI application.

main.py

    def create_app():
        app = ...
        return app

    uvicorn --factory main:create_app