Uvicorn

https://uvicorn.dev/
Admin
Uvicorn is an ASGI web server implementation for Python that supports HTTP/1.1 and WebSockets for...
Tokens:34,037
Snippets:332
Trust Score:8
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run Uvicorn from async environment with Server.serve()

Source: https://uvicorn.dev/

Use uvicorn.Server.serve() to run Uvicorn from an already running async environment. This example uses asyncio.run() to start the main coroutine.

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

```

--------------------------------

### Install project and dependencies

Source: https://uvicorn.dev/contributing

Navigate into the cloned directory and run the install script to set up the project and its dependencies.

```bash
$ cd uvicorn
$ scripts/install

```

--------------------------------

### Install zuvloop with uv

Source: https://uvicorn.dev/concepts/event-loop

Install the zuvloop package using the uv package manager.

```bash
uv add zuvloop

```

--------------------------------

### Install Uvicorn with standard extra using uv

Source: https://uvicorn.dev/installation

Installs Uvicorn with the 'standard' extra using the uv package manager.

```bash
uv add 'uvicorn[standard]'

```

--------------------------------

### Install winloop with uv

Source: https://uvicorn.dev/concepts/event-loop

Install the winloop package using the uv package manager.

```bash
uv add winloop

```

--------------------------------

### Install rloop with uv

Source: https://uvicorn.dev/concepts/event-loop

Install the rloop package using the uv package manager.

```bash
uv add rloop

```

--------------------------------

### Install Uvicorn with uv

Source: https://uvicorn.dev/installation

Installs Uvicorn with the minimal set of dependencies using the uv package manager.

```bash
uv add uvicorn

```

--------------------------------

### Install and run Hypercorn ASGI server

Source: https://uvicorn.dev/concepts/asgi

Install Hypercorn via pip and run an ASGI application with the command 'hypercorn app:App'. Hypercorn supports HTTP/1.1, HTTP/2, HTTP/3, and WebSockets.

```bash
pip install hypercorn
hypercorn app:App

```

--------------------------------

### Install and run Daphne ASGI server

Source: https://uvicorn.dev/concepts/asgi

Install Daphne via pip and run an ASGI application with the command 'daphne app:App'. Daphne supports HTTP/1.1, HTTP/2, and WebSockets.

```bash
pip install daphne
daphne app:App

```

--------------------------------

### Install Uvicorn with pip

Source: https://uvicorn.dev/installation

Installs Uvicorn with the minimal set of dependencies: h11 and click. On Python 3.10 or earlier, typing_extensions is also installed.

```bash
pip install uvicorn

```

--------------------------------

### Install winloop with pip

Source: https://uvicorn.dev/concepts/event-loop

Install the winloop package using pip. Winloop provides uvloop-like performance on Windows.

```bash
pip install winloop

```

--------------------------------

### Run uvicorn with HTTPS using SSL flags

Source: https://uvicorn.dev/deployment

Starts uvicorn with HTTPS using the --ssl-keyfile and --ssl-certfile flags. Requires a certificate and private key, e.g., from Let's Encrypt or mkcert for local development.

```bash
$ uvicorn main:app --port 5000 --ssl-keyfile=./key.pem --ssl-certfile=./cert.pem

```

--------------------------------

### Run the application with uvicorn

Source: https://uvicorn.dev/deployment/docker

Runs the ASGI application with uvicorn using uv. This starts the server on http://127.0.0.1:8000 by default.

```bash
uv run uvicorn main:app

```

--------------------------------

### Run Uvicorn programmatically with import string

Source: https://uvicorn.dev/deployment

Use uvicorn.run with an import string to start the server. Recommended over passing the app instance because it supports multiprocessing and reloading. Place the call inside the if __name__ == '__main__' block.

```python
import uvicorn

class App:
    ...

app = App()

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

--------------------------------

### Install zuvloop with pip

Source: https://uvicorn.dev/concepts/event-loop

Install the zuvloop package using pip. zuvloop requires CPython 3.14 or newer.

```bash
pip install zuvloop

```

--------------------------------

### Install zttp with pip

Source: https://uvicorn.dev/concepts/http-protocols

Installs the zttp HTTP parser package using pip. zttp is a sans-IO HTTP parser with a core written in Zig, with prebuilt wheels for CPython on Linux, macOS, and Windows.

```bash
pip install zttp

```

--------------------------------

### Install Uvicorn with standard extra using pip

Source: https://uvicorn.dev/installation

Installs Uvicorn with the 'standard' extra, which adds uvloop, httptools, websockets, watchfiles, python-dotenv, and PyYAML.

```bash
pip install 'uvicorn[standard]'

```

--------------------------------

### Run Uvicorn programmatically with uvicorn.run()

Source: https://uvicorn.dev/

Programmatic equivalent of the uvicorn command line interface. Uses uvicorn.run() to start the server on port 5000 with info logging.

```python
import uvicorn

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

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

```

--------------------------------

### Install rloop with pip

Source: https://uvicorn.dev/concepts/event-loop

Install the rloop package using pip. rloop is experimental and only available on Unix systems.

```bash
pip install rloop

```

--------------------------------

### HTTP scope example

Source: https://uvicorn.dev/concepts/asgi

Shows the structure of an ASGI scope dictionary for an incoming HTTP request, including method, path, headers, and server details.

```python
{
    'type': 'http',
    'scheme': 'http',
    'root_path': '',
    'server': ('127.0.0.1', 8000),
    'http_version': '1.1',
    'method': 'GET',
    'path': '/',
    'headers': [
        (b'host', b'127.0.0.1:8000'),
        (b'user-agent', b'curl/7.51.0'),
        (b'accept', b'*/*')
    ]
}

```

--------------------------------

### Simple ASGI application in main.py

Source: https://uvicorn.dev/

A minimal ASGI application that responds with 'Hello, world!' over HTTP. It asserts the scope type is 'http' and sends a response start and body.

```python
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!',
    })

```

--------------------------------

### Select event loop with --loop option

Source: https://uvicorn.dev/concepts/event-loop

Use the --loop option to choose an event loop implementation. The default is 'auto', which selects uvloop if installed, otherwise asyncio.

```bash
uvicorn main:app --loop <auto|asyncio|uvloop|zuvloop>

```

--------------------------------

### Run Uvicorn with --http option

Source: https://uvicorn.dev/concepts/http-protocols

Selects the HTTP protocol implementation for Uvicorn. The value can be auto, h11, httptools, or zttp. Default is auto, which uses httptools if installed, otherwise h11.

```bash
uvicorn main:app --http <auto|h11|httptools|zttp>

```

--------------------------------

### Serve documentation locally

Source: https://uvicorn.dev/contributing

Run the documentation site locally to preview changes.

```bash
$ scripts/docs serve

```

--------------------------------

### Install uvicorn-worker package

Source: https://uvicorn.dev/deployment

Install the uvicorn-worker package as a replacement for the deprecated uvicorn.workers module.

```bash
python -m pip install uvicorn-worker
```

--------------------------------

### Initialize a new project with uv

Source: https://uvicorn.dev/deployment/docker

Initializes a new Python project named 'app' using the uv package manager. This creates the basic project structure with main.py, pyproject.toml, and README.md.

```bash
uv init app

```

--------------------------------

### Run Uvicorn with Config and Server instances

Source: https://uvicorn.dev/

Provides more control over configuration and server lifecycle by creating uvicorn.Config and uvicorn.Server instances and calling server.run().

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

```

--------------------------------

### Project structure after uv init

Source: https://uvicorn.dev/deployment/docker

Shows the directory structure created by 'uv init app'. It includes main.py, pyproject.toml, and README.md.

```text
app/
├── main.py
├── pyproject.toml
└── README.md

```

--------------------------------

### Uvicorn startup output

Source: https://uvicorn.dev/deployment/docker

Expected output when running 'uv run uvicorn main:app'. It shows the server startup messages and the URL where the app is served.

```text
INFO:     Started server process [62727]
INFO:     Waiting for application startup.
INFO:     ASGI 'lifespan' protocol appears unsupported.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

```

--------------------------------

### Build and run the Docker image

Source: https://uvicorn.dev/deployment/docker

Builds the Docker image with tag 'my-app' and runs a container mapping port 8000 to the host. This is used to verify the Dockerfile works.

```bash
docker build -t my-app .
docker run -p 8000:8000 my-app

```

--------------------------------

### Simple ASGI application in main.py

Source: https://uvicorn.dev/deployment/docker

A minimal ASGI application that returns a plain text 'Hello, world!' response. This is the main.py file created in the project and is used to test the uvicorn server.

```python
async def app(scope, receive, send):
    body = "Hello, world!"
    await send(
        {
            "type": "http.response.start",
            "status": 200,
            "headers": [
                [b"content-type", b"text/plain"],
                [b"content-length", len(body)],
            ],
        }
    )
    await send(
        {
            "type": "http.response.body",
            "body": body.encode("utf-8"),
        }
    )

```

--------------------------------

### HTTP response messages

Source: https://uvicorn.dev/concepts/asgi

Sends the start and body messages for an HTTP response, setting status and headers, then the body content.

```python
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!',
})

```

--------------------------------

### ASGI scope http_version for HTTP/2

Source: https://uvicorn.dev/concepts/http2

When a request comes in over HTTP/2, the ASGI scope has http_version set to "2". This example prints the HTTP version.

```python
async def app(scope, receive, send):
    assert scope["type"] == "http"
    print(f"HTTP Version: {scope['http_version']}")  # "2" for HTTP/2

```

--------------------------------

### Enable HTTP/2 with zttp

Source: https://uvicorn.dev/concepts/http-protocols

Runs Uvicorn with zttp and enables experimental HTTP/2 negotiation. HTTP/2 support is opt-in and experimental, not suited for production.

```bash
uvicorn main:app --http zttp --http2

```

--------------------------------

### Run Gunicorn with UvicornWorker

Source: https://uvicorn.dev/deployment

Start Gunicorn with four worker processes using the UvicornWorker class, which uses uvloop and httptools. Some Uvicorn options like --limit-concurrency are not supported with Gunicorn.

```bash
gunicorn -w 4 -k uvicorn.workers.UvicornWorker
```

--------------------------------

### Programmatic dictConfig with Python dictionary

Source: https://uvicorn.dev/concepts/logging

Pass a logging configuration dictionary directly to uvicorn.run() using the log_config parameter. This example defines the same formatters and handlers as the YAML/JSON files, and then runs the application with that configuration.

```python
import uvicorn

log_config = {
    "version": 1,
    "disable_existing_loggers": False,
    "formatters": {
        "default": {
            "()": "uvicorn.logging.DefaultFormatter",
            "fmt": "%(asctime)s - %(levelprefix)s %(message)s",
            "datefmt": "%Y-%m-%d %H:%M:%S",
        },
        "access": {
            "()": "uvicorn.logging.AccessFormatter",
            "fmt": '%(asctime)s - %(levelprefix)s %(client_addr)s - "%(request_line)s" %(status_code)s',
            "datefmt": "%Y-%m-%d %H:%M:%S",
        },
    },
    "handlers": {
        "default": {
            "formatter": "default",
            "class": "logging.StreamHandler",
            "stream": "ext://sys.stderr",
        },
        "access": {
            "formatter": "access",
            "class": "logging.StreamHandler",
            "stream": "ext://sys.stdout",
        },
    },
    "loggers": {
        "uvicorn": {"handlers": ["default"], "level": "INFO", "propagate": False},
        "uvicorn.error": {"level": "INFO"},
        "uvicorn.access": {"handlers": ["access"], "level": "INFO", "propagate": False},
    },
}

uvicorn.run("main:app", log_config=log_config)

```

--------------------------------

### Subclass UvicornWorker to pass config kwargs

Source: https://uvicorn.dev/deployment

Subclass UvicornWorker and set CONFIG_KWARGS to pass Uvicorn configuration arguments to Gunicorn workers. Example sets loop to asyncio, http to h11, and lifespan to off.

```python
from uvicorn.workers import UvicornWorker

class MyUvicornWorker(UvicornWorker):
    CONFIG_KWARGS = {"loop": "asyncio", "http": "h11", "lifespan": "off"}
```

--------------------------------

### Programmatic Configuration: uvicorn.run("main:app", host="0.0.0.0", port=8000)

Source: https://uvicorn.dev/settings

Run Uvicorn programmatically using keyword arguments. When using reload=True or workers=NUM, place uvicorn.run inside an if __name__ == '__main__' clause.

```python
uvicorn.run("main:app", host="0.0.0.0", port=8000)
```
Tokens:
Raw