---
[](https://github.com/Kludex/uvicorn/actions)
[](https://pypi.python.org/pypi/uvicorn)
[](https://pypi.org/project/uvicorn)
[](https://discord.gg/RxKUF5JuHs)
---
**Documentation**: [https://uvicorn.dev](https://uvicorn.dev)
**Source Code**: [https://www.github.com/Kludex/uvicorn](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][asgi] 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, HTTP/2 and WebSockets.
## Quickstart
Install using `pip`:
```shell
$ pip install uvicorn
```
This will install uvicorn with minimal (pure Python) dependencies.
```shell
$ pip install 'uvicorn[standard]'
```
This will install uvicorn with "Cython-based" dependencies (where possible) and other "optional extras".
In this context, "Cython-based" means the following:
- the event loop `uvloop` will be installed and used if possible.
- the http protocol will be handled by `httptools` if possible.
Moreover, "optional extras" means that:
- the websocket protocol will be handled by `websockets` (should you want to use `wsproto` you'd need to install it manually) if possible.
- the `--reload` flag in development mode will use `watchfiles`.
- `python-dotenv` will be installed should you want to use the `--env-file` option.
- `PyYAML` will be installed to allow you to provide a `.yaml` file to `--log-config`, if desired.
Create an application, in `example.py`:
```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'),
],
})
await send({
'type': 'http.response.body',
'body': b'Hello, world!',
})
```
Run the server:
```shell
$ uvicorn example:app
```
---
## Why ASGI?
Most well established Python Web frameworks started out as WSGI-based frameworks.
WSGI applications are a single, synchronous callable that takes a request and returns a response.
This doesnβt allow for long-lived connections, like you get with long-poll HTTP or WebSocket connections,
which WSGI doesn't support well.
Having an async concurrency model also allows for options such as lightweight background tasks,
and can be less of a limiting factor for endpoints that have long periods being blocked on network
I/O such as dealing with slow HTTP requests.
---
## Alternative ASGI servers
A strength of the ASGI protocol is that it decouples the server implementation
from the application framework. This allows for an ecosystem of interoperating
webservers and application frameworks.
### Daphne
The first ASGI server implementation, originally developed to power Django Channels, is [the Daphne webserver][daphne].
It is run widely in production, and supports HTTP/1.1, HTTP/2, and WebSockets.
Any of the example applications given here can equally well be run using `daphne` instead.
```
$ pip install daphne
$ daphne app:App
```
### Hypercorn
[Hypercorn][hypercorn] was initially part of the Quart web framework, before
being separated out into a standalone ASGI server.
Hypercorn supports HTTP/1.1, HTTP/2, and WebSockets.
It also supports [the excellent `trio` async framework][trio], as an alternative to `asyncio`.
```
$ pip install hypercorn
$ hypercorn app:App
```
### Mangum
[Mangum][mangum] is an adapter for using ASGI applications with AWS Lambda & API Gateway.
### Granian
[Granian][granian] is an ASGI compatible Rust HTTP server which supports HTTP/2, TLS and WebSockets.
---
Uvicorn is BSD licensed code. Designed & crafted with care. — π¦ —
[asgi]: https://asgi.readthedocs.io/en/latest/
[daphne]: https://github.com/django/daphne
[hypercorn]: https://github.com/pgjones/hypercorn
[trio]: https://trio.readthedocs.io
[mangum]: https://github.com/jordaneremieff/mangum
[granian]: https://github.com/emmett-framework/granian
uvicorn-0.53.0/docs/ 0000775 0000000 0000000 00000000000 15251720332 0014214 5 ustar 00root root 0000000 0000000 uvicorn-0.53.0/docs/CNAME 0000664 0000000 0000000 00000000020 15251720332 0014752 0 ustar 00root root 0000000 0000000 www.uvicorn.org
uvicorn-0.53.0/docs/concepts/ 0000775 0000000 0000000 00000000000 15251720332 0016032 5 ustar 00root root 0000000 0000000 uvicorn-0.53.0/docs/concepts/asgi.md 0000664 0000000 0000000 00000017730 15251720332 0017307 0 ustar 00root root 0000000 0000000 ## ASGI
**Uvicorn** uses the [ASGI specification](https://asgi.readthedocs.io/en/latest/) for interacting with an application.
The application should expose an async callable which takes three arguments:
* `scope` - A dictionary containing information about the incoming connection.
* `receive` - A channel on which to receive incoming messages from the server.
* `send` - A channel on which to send outgoing messages to the server.
Two common patterns you might use are either function-based applications:
```python
async def app(scope, receive, send):
assert scope['type'] == 'http'
...
```
Or instance-based applications:
```python
class App:
async def __call__(self, scope, receive, send):
assert scope['type'] == 'http'
...
app = App()
```
It's good practice for applications to raise an exception on scope types
that they do not handle.
The content of the `scope` argument, and the messages expected by `receive` and `send` depend on the protocol being used.
The format for HTTP messages is described in the [ASGI HTTP Message format](https://asgi.readthedocs.io/en/latest/specs/www.html).
### HTTP Scope
An incoming HTTP request might have a connection `scope` like this:
```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'*/*')
]
}
```
### HTTP Messages
The instance coroutine communicates back to the server by sending messages to the `send` coroutine.
```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!',
})
```
### Requests & responses
Here's an example that displays the method and path used in the incoming request:
```python
async def app(scope, receive, send):
"""
Echo the method and path back in an HTTP response.
"""
assert scope['type'] == 'http'
body = f'Received {scope["method"]} request to {scope["path"]}'
await send({
'type': 'http.response.start',
'status': 200,
'headers': [
[b'content-type', b'text/plain'],
]
})
await send({
'type': 'http.response.body',
'body': body.encode('utf-8'),
})
```
### Reading the request body
You can stream the request body without blocking the asyncio task pool,
by fetching messages from the `receive` coroutine.
```python
async def read_body(receive):
"""
Read and return the entire body from an incoming ASGI message.
"""
body = b''
more_body = True
while more_body:
message = await receive()
body += message.get('body', b'')
more_body = message.get('more_body', False)
return body
async def app(scope, receive, send):
"""
Echo the request body back in an HTTP response.
"""
body = await read_body(receive)
await send({
'type': 'http.response.start',
'status': 200,
'headers': [
(b'content-type', b'text/plain'),
(b'content-length', str(len(body)).encode())
]
})
await send({
'type': 'http.response.body',
'body': body,
})
```
### Streaming responses
You can stream responses by sending multiple `http.response.body` messages to
the `send` coroutine.
```python
import asyncio
async def app(scope, receive, send):
"""
Send a slowly streaming HTTP response back to the client.
"""
await send({
'type': 'http.response.start',
'status': 200,
'headers': [
[b'content-type', b'text/plain'],
]
})
for chunk in [b'Hello', b', ', b'world!']:
await send({
'type': 'http.response.body',
'body': chunk,
'more_body': True
})
await asyncio.sleep(1)
await send({
'type': 'http.response.body',
'body': b'',
})
```
---
## Why ASGI?
Most well established Python Web frameworks started out as WSGI-based frameworks.
WSGI applications are a single, synchronous callable that takes a request and returns a response.
This doesnβt allow for long-lived connections, like you get with long-poll HTTP or WebSocket connections,
which WSGI doesn't support well.
Having an async concurrency model also allows for options such as lightweight background tasks,
and can be less of a limiting factor for endpoints that have long periods being blocked on network
I/O such as dealing with slow HTTP requests.
---
## Alternative ASGI servers
A strength of the ASGI protocol is that it decouples the server implementation
from the application framework. This allows for an ecosystem of interoperating
webservers and application frameworks.
### Daphne
The first ASGI server implementation, originally developed to power Django Channels, is
[the Daphne webserver](https://github.com/django/daphne).
It is run widely in production, and supports HTTP/1.1, HTTP/2, and WebSockets.
Any of the example applications given here can equally well be run using `daphne` instead.
```shell
pip install daphne
daphne app:App
```
### Hypercorn
[Hypercorn](https://github.com/pgjones/hypercorn) was initially part of the Quart web framework,
before being separated out into a standalone ASGI server.
Hypercorn supports HTTP/1.1, HTTP/2, HTTP/3 and WebSockets.
```shell
pip install hypercorn
hypercorn app:App
```
---
## ASGI frameworks
You can use Uvicorn, Daphne, or Hypercorn to run any ASGI framework.
For small services you can also write ASGI applications directly.
### Starlette
[Starlette](https://github.com/Kludex/starlette) is a lightweight ASGI framework/toolkit.
It is ideal for building high performance asyncio services, and supports both HTTP and WebSockets.
### Django Channels
The ASGI specification was originally designed for use with [Django Channels](https://channels.readthedocs.io/en/latest/).
Channels is a little different to other ASGI frameworks in that it provides
an asynchronous frontend onto a threaded-framework backend. It allows Django
to support WebSockets, background tasks, and long-running connections,
with application code still running in a standard threaded context.
### Quart
[Quart](https://pgjones.gitlab.io/quart/) is a Flask-like ASGI web framework.
### FastAPI
[**FastAPI**](https://github.com/tiangolo/fastapi) is an API framework based on **Starlette** and **Pydantic**, heavily inspired by previous server versions of **APIStar**.
You write your API function parameters with Python 3.6+ type declarations and get automatic data conversion, data validation, OpenAPI schemas (with JSON Schemas) and interactive API documentation UIs.
### BlackSheep
[BlackSheep](https://www.neoteroi.dev/blacksheep/) is a web framework based on ASGI, inspired by Flask and ASP.NET Core.
Its most distinctive features are built-in support for dependency injection, automatic binding of parameters by request handler's type annotations, and automatic generation of OpenAPI documentation and Swagger UI.
### Falcon
[Falcon](https://falconframework.org) is a minimalist REST and app backend framework for Python, with a focus on reliability, correctness, and performance at scale.
### Muffin
[Muffin](https://github.com/klen/muffin) is a fast, lightweight and asynchronous ASGI web-framework for Python 3.
### Litestar
[Litestar](https://litestar.dev) is a powerful, lightweight and flexible ASGI framework.
It includes everything that's needed to build modern APIs - from data serialization and validation to websockets, ORM integration, session management, authentication and more.
### Panther
[Panther](https://PantherPy.github.io/) is a fast & friendly web framework for building async APIs with Python 3.10+.
It has built-in Document-oriented Database, Caching System, Authentication and Permission Classes, Visual API Monitoring and also supports Websocket, Throttling, Middlewares.
uvicorn-0.53.0/docs/concepts/event-loop.md 0000664 0000000 0000000 00000005753 15251720332 0020456 0 ustar 00root root 0000000 0000000 # Event Loop
Uvicorn provides three event loop implementations that you can choose from using the [`--loop`](../settings.md#implementation) option:
```bash
uvicorn main:app --loop
```
By default, Uvicorn uses `--loop auto`, which automatically selects:
1. **uvloop** - If [uvloop](https://github.com/MagicStack/uvloop) is installed, Uvicorn will use it for maximum performance
2. **asyncio** - If uvloop is not available, Uvicorn falls back to Python's built-in asyncio event loop
Since `uvloop` is not compatible with Windows or PyPy, it is not available on these platforms.
On Windows, the asyncio implementation uses the standard [`ProactorEventLoop`][asyncio.ProactorEventLoop] in single-process mode.
When running with `--reload` or multiple workers, it uses [`SelectorEventLoop`][asyncio.SelectorEventLoop] instead.
??? info "Why can `ProactorEventLoop` fail with multiple processes on Windows?"
If you want to know more about it, you can read the issue [#cpython/122240](https://github.com/python/cpython/issues/122240).
## zuvloop
[`zuvloop`](https://zuvloop.marcelotryle.com/) is an `asyncio` event loop powered by libuv and written in Zig.
It requires CPython 3.14 or newer.
Install `zuvloop` separately:
=== "pip"
```bash
pip install zuvloop
```
=== "uv"
```bash
uv add zuvloop
```
Then select it explicitly:
```bash
uvicorn main:app --loop zuvloop
```
Uvicorn does not include `zuvloop` in the `standard` extra or select it with `--loop auto`.
## Custom Event Loop
You can use custom event loop implementations by specifying a module path and function name using the colon notation:
```bash
uvicorn main:app --loop :
```
The function should return a callable that creates a new event loop instance.
### rloop
[rloop](https://github.com/gi0baro/rloop) is an experimental AsyncIO event loop implemented in Rust on top of the [mio](https://github.com/tokio-rs/mio) crate. It aims to provide high performance through Rust's systems programming capabilities.
You can install it with:
=== "pip"
```bash
pip install rloop
```
=== "uv"
```bash
uv add rloop
```
You can run `uvicorn` with `rloop` with the following command:
```bash
uvicorn main:app --loop rloop:new_event_loop
```
!!! warning "Experimental"
rloop is currently **experimental** and **not suited for production usage**. It is only available on **Unix systems**.
### Winloop
[Winloop](https://github.com/Vizonex/Winloop) is an alternative library that brings uvloop-like performance to Windows. Since uvloop is based on libuv and doesn't support Windows, Winloop provides a Windows-compatible implementation with significant performance improvements over the standard Windows event loop policies.
You can install it with:
=== "pip"
```bash
pip install winloop
```
=== "uv"
```bash
uv add winloop
```
You can run `uvicorn` with `Winloop` with the following command:
```bash
uvicorn main:app --loop winloop:new_event_loop
```
uvicorn-0.53.0/docs/concepts/http-protocols.md 0000664 0000000 0000000 00000003565 15251720332 0021366 0 ustar 00root root 0000000 0000000 # HTTP Protocols
Uvicorn provides several HTTP protocol implementations that you can choose from using the [`--http`](../settings.md#implementation) option:
```bash
uvicorn main:app --http
```
By default, Uvicorn uses `--http auto`, which automatically selects:
1. **httptools** - If [httptools](https://github.com/MagicStack/httptools) is installed, Uvicorn will use it for maximum performance
2. **h11** - If httptools is not available, Uvicorn falls back to [h11](https://github.com/python-hyper/h11)
## h11
[h11](https://github.com/python-hyper/h11) is a pure Python HTTP/1.1 implementation. It is a required dependency of Uvicorn, so it is always available, and it is the only implementation compatible with PyPy.
## httptools
[httptools](https://github.com/MagicStack/httptools) is a Python binding for the Node.js HTTP parser. It is installed as part of the `uvicorn[standard]` optional extras, and provides greater performance than h11, but is not compatible with PyPy.
## zttp
[zttp](https://zttp.marcelotryle.com/) is a sans-IO HTTP parser for Python with a core written in Zig. Prebuilt wheels are available for CPython on Linux, macOS and Windows.
You can install it with:
=== "pip"
```bash
pip install zttp
```
=== "uv"
```bash
uv add zttp
```
You can run `uvicorn` with `zttp` with the following command:
```bash
uvicorn main:app --http zttp
```
The `zttp` implementation serves HTTP/1.1 by default. This keeps experimental HTTP/2
support opt-in. You can enable HTTP/2 negotiation with:
```bash
uvicorn main:app --http zttp --http2
```
See the [HTTP/2 documentation](http2.md) for details.
!!! warning "Experimental"
zttp support is currently **experimental** and **not suited for production usage**. If you try it out, please report any issues or feedback on the [issue tracker](https://github.com/Kludex/uvicorn/issues).
uvicorn-0.53.0/docs/concepts/http2.md 0000664 0000000 0000000 00000017361 15251720332 0017425 0 ustar 00root root 0000000 0000000 **Uvicorn** has experimental support for HTTP/2, built on the [`zttp`](https://zttp.marcelotryle.com/)
parser.
!!! warning "Experimental Feature"
HTTP/2 support is currently **experimental** and is **not enabled by default**.
## Overview
HTTP/2 introduces several key features:
- **Multiplexing**: Multiple requests and responses can be sent simultaneously over a single TCP connection
- **Header compression**: HTTP headers are compressed using HPACK, reducing overhead
- **Binary protocol**: More efficient parsing compared to HTTP/1.1's text-based format
## Enabling HTTP/2
HTTP/2 support requires the `zttp` package:
```bash
pip install zttp
```
To enable it, select the `zttp` HTTP implementation and pass `--http2`:
=== "Command Line"
```bash
uvicorn main:app --http zttp --http2
```
=== "Programmatic"
```python
import uvicorn
uvicorn.run("main:app", http="zttp", http2=True)
```
The `--http2` option makes `zttp` serve both HTTP versions. Each connection is dispatched
to HTTP/1.1 or HTTP/2 depending on what the client speaks. Without this option, `zttp`
serves HTTP/1.1 only. This default keeps experimental HTTP/2 support opt-in.
## Connection Methods
### h2: HTTP/2 over TLS (Recommended)
When using HTTPS, HTTP/2 is negotiated via **ALPN** (Application-Layer Protocol Negotiation)
during the TLS handshake. This is the most common way to use HTTP/2, and the only one web
browsers support.
```mermaid
sequenceDiagram
participant Client
participant Server
Note over Client,Server: TLS Handshake with ALPN
Client->>Server: ClientHello
Note right of Client: ALPN: h2, http/1.1
Server->>Client: ServerHello
Note right of Server: ALPN: h2
Note over Client,Server: TLS Handshake Complete
Client->>Server: Connection Preface
Note right of Client: PRI * HTTP/2.0
Client->>Server: Client SETTINGS Frame
Server->>Client: Server SETTINGS Frame
Note over Client,Server: HTTP/2 Connection Established
Client->>Server: HEADERS (Stream 1)
Server->>Client: HEADERS + DATA (Stream 1)
```
For testing it locally, you can generate a self-signed certificate:
```bash
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/CN=localhost"
```
Then create a simple ASGI application:
```python title="main.py"
async def app(scope, receive, send):
await send({"type": "http.response.start", "status": 200, "headers": []})
await send({"type": "http.response.body", "body": b"ok"})
```
Run Uvicorn with `--http zttp --http2` and the SSL certificate files:
```bash
uvicorn main:app --http zttp --http2 --ssl-keyfile key.pem --ssl-certfile cert.pem
```
You can test the connection using curl (`-k` skips certificate verification for self-signed certs):
```bash
curl -v --http2 -k https://localhost:8000/
```
### h2c: HTTP/2 Cleartext with Prior Knowledge
On cleartext connections, Uvicorn accepts clients that speak HTTP/2 directly - known as
"prior knowledge" h2c. The client opens the connection with the HTTP/2 preface instead of an
HTTP/1.1 request, and Uvicorn switches protocols on the spot.
```mermaid
sequenceDiagram
participant Client
participant Server
Note over Client,Server: Cleartext TCP Connection
Client->>Server: Connection Preface
Note right of Client: PRI * HTTP/2.0
Client->>Server: Client SETTINGS Frame
Server->>Client: Server SETTINGS Frame
Note over Client,Server: HTTP/2 Connection Established
Client->>Server: HEADERS + DATA (Stream 1)
Server->>Client: HEADERS + DATA (Stream 1)
```
Using the same `main.py`:
```bash
uvicorn main:app --http zttp --http2
```
```bash
curl -v --http2-prior-knowledge http://localhost:8000/
```
This is the mechanism proxies use for cleartext HTTP/2 upstreams, so HTTP/2 between a proxy
and Uvicorn works without TLS. How you enable it is proxy-specific: Traefik and Caddy use
`h2c://` upstream URLs, while Envoy configures HTTP/2 on the cluster.
!!! warning "h2c is cleartext"
Prior-knowledge h2c provides no transport encryption or peer authentication. Limit it to
trusted private networks (e.g. the proxy-to-Uvicorn hop); use HTTP/2 over TLS for any
untrusted hop.
!!! warning
The HTTP/1.1 `Upgrade: h2c` mechanism is **not** supported: an upgrade request is served
as plain HTTP/1.1, which RFC 7540 explicitly allows. Browsers do not support h2c at all -
they only speak HTTP/2 over TLS.
## ASGI Scope
When a request comes in over HTTP/2, the ASGI scope has `http_version` set to `"2"`:
```python
async def app(scope, receive, send):
assert scope["type"] == "http"
print(f"HTTP Version: {scope['http_version']}") # "2" for HTTP/2
```
## Using with Reverse Proxies
In production, Uvicorn is typically deployed behind a reverse proxy like Nginx, Caddy, or HAProxy.
The proxy can terminate TLS and serve HTTP/2 to clients, while talking either HTTP/1.1 or
HTTP/2 to Uvicorn.
```mermaid
flowchart LR
Client <-->|HTTP/2 over TLS| Proxy
Proxy <-->|HTTP/1.1 or HTTP/2| Uvicorn
style Client fill:#e1f5fe
style Proxy fill:#fff3e0
style Uvicorn fill:#e8f5e9
```
### Proxy HTTP/2 Upstream Support
**HTTP/2 upstream** refers to the protocol used between the proxy and Uvicorn. While all modern
proxies support HTTP/2 for client connections, support for HTTP/2 to backend servers varies.
**Multiplexing** is HTTP/2's ability to send multiple requests simultaneously over a single TCP
connection. Some proxies support HTTP/2 upstream but open a new connection per request, which
means they don't truly multiplex.
Here's the state of proxy support at the time of writing:
| Proxy | HTTP/2 Upstream | Multiplexing | Enabled by | Documentation |
|-------|-----------------|--------------|------------|---------------|
| **Envoy** | Yes | Yes | HTTP/2 protocol options on the cluster | [Connection Pooling Docs](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/connection_pooling) |
| **Caddy** | Yes | Yes | `h2c://` upstream (experimental), or `versions 2` in the transport for TLS | [reverse_proxy Docs](https://caddyserver.com/docs/caddyfile/directives/reverse_proxy) |
| **HAProxy** | Yes | Yes | `proto h2` on the server line (cleartext), `ssl alpn h2,http/1.1` (TLS) | [HTTP/2 Docs](https://www.haproxy.com/documentation/hapee/latest/load-balancing/protocols/http-2/) |
| **Traefik** | Yes | Yes | `h2c://` service URL | [ServersTransport Docs](https://doc.traefik.io/traefik/routing/services/) |
| **Apache** | Yes (2.4.19+) | No | `h2://` / `h2c://` in `ProxyPass` (no HTTP/1.1 fallback) | [mod_proxy_http2 Docs](https://httpd.apache.org/docs/current/mod/mod_proxy_http2.html) |
| **Nginx** | Yes (1.29.4+) | No | `proxy_http_version 2;` (requires `ngx_http_v2_module`) | [ngx_http_proxy_module Docs](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_http_version) |
Uvicorn supports both upstream flavors: cleartext prior-knowledge h2c, and HTTP/2 over TLS
via ALPN when the proxy-to-Uvicorn hop uses TLS.
### Performance Considerations
HTTP/2 provides the most benefit when:
- **High latency connections**: Multiplexing reduces round-trip overhead
- **Many concurrent requests**: Multiple streams share a single connection
- **Large headers**: HPACK compression reduces header overhead
For internal, low-latency connections (like proxy to backend), HTTP/1.1 with keepalive often
performs comparably to HTTP/2. It is simpler to configure and debug, which is why it remains the
recommended default for most deployments.
## Current Limitations
The implementation is young, and some protocol features are not complete yet:
- HTTP/2 server push and `Expect: 100-continue` are not supported.
- WebSockets over HTTP/2 (RFC 8441 extended `CONNECT`) are not supported. With `--http zttp --http2`,
WebSocket connections still work - they are served over HTTP/1.1.
uvicorn-0.53.0/docs/concepts/lifespan.md 0000664 0000000 0000000 00000010234 15251720332 0020155 0 ustar 00root root 0000000 0000000 Since Uvicorn is an ASGI server, it supports the
[ASGI lifespan protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html).
This allows you to run **startup** and **shutdown** events for your application.
The lifespan protocol is useful for initializing resources that need to be available throughout
the lifetime of the application, such as database connections, caches, or other services.
Keep in mind that the lifespan is executed **only once per application instance**. If you have
multiple workers, each worker will execute the lifespan independently.
## Lifespan Architecture
The lifespan protocol runs as a sibling task alongside your main application, allowing both to execute concurrently.
Let's see how Uvicorn handles the lifespan and main application tasks:
```mermaid
sequenceDiagram
participant Server as Uvicorn Server
participant LifespanTask as Lifespan Task
participant AppTask as Application Task
participant UserApp as User Application
Note over Server: β Server starts
Server->>+LifespanTask: spawn_task(lifespan_handler)
LifespanTask->>UserApp: {"type": "lifespan.startup"}
Note over UserApp: Initialize databases, caches, etc.
UserApp-->>LifespanTask: {"type": "lifespan.startup.complete"}
LifespanTask->>Server: β Startup complete
Server->>+AppTask: spawn_task(application_handler)
Note over AppTask: β Ready for requests
rect rgb(240, 248, 255)
Note over LifespanTask, AppTask: Both tasks running concurrently
par Lifespan maintains state
LifespanTask->>LifespanTask: Keep lifespan connection alive
and Application serves requests
AppTask->>UserApp: HTTP/WebSocket requests
UserApp-->>AppTask: Responses
end
end
Note over Server: Shutdown signal received
Server->>AppTask: Stop accepting new connections
AppTask->>AppTask: Complete pending requests
LifespanTask->>UserApp: {"type": "lifespan.shutdown"}
Note over UserApp: Cleanup databases, caches, etc.
UserApp-->>LifespanTask: {"type": "lifespan.shutdown.complete"}
LifespanTask->>-Server: Lifespan task complete
AppTask->>-Server: Application task complete
Note over Server: β Server stopped
```
Having the lifespan task run as a sibling task is a deliberate design choice. It could have been implemented as a parent task that spawns the
application task. This decision has the implication that if you create a [`ContextVar`][contextvars.ContextVar]
in the lifespan task, it will not be available in the application task.
## Usage
Let's see an example of a minimal (but complete) ASGI application that implements the lifespan protocol:
```python title="ASGI application with lifespan" hl_lines="3-11"
async def app(scope, receive, send):
if scope['type'] == 'lifespan':
while True:
message = await receive()
if message['type'] == 'lifespan.startup':
print("Application is starting up...")
await send({'type': 'lifespan.startup.complete'})
elif message['type'] == 'lifespan.shutdown':
print("Application is shutting down...")
await send({'type': 'lifespan.shutdown.complete'})
return
elif scope['type'] == 'http':
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!'})
else:
raise RuntimeError("This server doesn't support WebSocket.")
```
You can run the above application with `uvicorn main:app`. Then you'll see the print statements when the
application starts. You can also try to send some HTTP requests to it, and it will respond with "Hello, World!".
And if you stop the server (`CTRL + C`), it will print `"Application is shutting down..."`.
## Disabling Lifespan
If you want to disable the lifespan protocol, you can do so by setting the `lifespan` option to `off` when running Uvicorn:
```bash
uvicorn main:app --lifespan off
```
By default, Uvicorn will automatically enable the lifespan protocol if the application supports it.
uvicorn-0.53.0/docs/concepts/logging.md 0000664 0000000 0000000 00000021024 15251720332 0020001 0 ustar 00root root 0000000 0000000 Uvicorn uses Python's built-in [`logging`](https://docs.python.org/3/library/logging.html)
module, and provides three loggers out of the box:
| Logger name | Purpose |
|------------------|----------------------------------------------------|
| `uvicorn` | Parent logger (rarely used directly) |
| `uvicorn.error` | Server-level messages (startup, shutdown, errors) |
| `uvicorn.access` | Per-request access log lines |
!!! note
Despite its name, `uvicorn.error` is **not** limited to error messages.
It is the general-purpose server logger, similar to how Gunicorn names its
main logger. See [#562](https://github.com/encode/uvicorn/issues/562) for
background.
## Default Configuration
By default, Uvicorn applies the following
[`dictConfig()`](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig)
configuration:
```python
LOGGING_CONFIG = {
"version": 1,
"disable_existing_loggers": False,
"formatters": {
"default": {
"()": "uvicorn.logging.DefaultFormatter",
"fmt": "%(levelprefix)s %(message)s",
"use_colors": None,
},
"access": {
"()": "uvicorn.logging.AccessFormatter",
"fmt": '%(levelprefix)s %(client_addr)s - "%(request_line)s" %(status_code)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},
},
}
```
## Custom Logging Configuration
You can supply a custom logging configuration file with the `--log-config`
option (or `log_config` when calling `uvicorn.run()`).
Uvicorn supports three file formats:
| Extension | Loader | Notes |
|----------------|------------------------------|---------------------------------------------|
| `.json` | `logging.config.dictConfig` | Standard JSON `dictConfig` schema. |
| `.yaml`/`.yml` | `logging.config.dictConfig` | Requires **PyYAML** (`uvicorn[standard]`). |
| Any other | `logging.config.fileConfig` | Classic INI-style format. |
### YAML Example
Create a file named `log_config.yaml`:
```yaml
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"
use_colors: null
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
```
Then pass it to Uvicorn:
=== "CLI"
```bash
uvicorn main:app --log-config log_config.yaml
```
=== "Programmatic"
```python
uvicorn.run("main:app", log_config="log_config.yaml")
```
### JSON Example
Create a file named `log_config.json`:
```json
{
"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",
"use_colors": null
},
"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
}
}
}
```
### Programmatic `dictConfig`
You can also pass a dictionary directly when running programmatically:
```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)
```
## Common Recipes
### Writing Logs to a File
To write Uvicorn's server logs to a file in addition to the console, add a `FileHandler` to the `uvicorn` logger:
```yaml
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"
use_colors: false
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
file:
formatter: default
class: logging.FileHandler
filename: uvicorn.log
loggers:
uvicorn:
handlers:
- default
- file
level: INFO
propagate: false
uvicorn.error:
level: INFO
uvicorn.access:
handlers:
- access
level: INFO
propagate: false
```
In this example, `uvicorn.access` still writes to stdout only. To write access
logs to the file as well, add `file` to the `uvicorn.access.handlers` list.
### Disabling Access Logs
Use the `--no-access-log` CLI flag, or set `access_log=False` programmatically.
This removes all handlers from `uvicorn.access` without affecting the
`uvicorn.error` logger.
### Disabling Colors
Pass `--no-use-colors` on the command line, or set `use_colors=False`
programmatically. When using a custom `--log-config`, set `use_colors: false`
on each formatter that extends `uvicorn.logging.ColourizedFormatter`.
### Using a Standard Formatter
If you do not need Uvicorn's colorized output, you can use the standard
`logging.Formatter` instead:
```yaml
version: 1
disable_existing_loggers: false
formatters:
default:
format: "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
datefmt: "%Y-%m-%d %H:%M:%S"
handlers:
default:
formatter: default
class: logging.StreamHandler
stream: ext://sys.stderr
loggers:
uvicorn:
handlers:
- default
level: INFO
propagate: false
uvicorn.error:
level: INFO
uvicorn.access:
handlers:
- default
level: INFO
propagate: false
```
!!! warning
When using a standard `logging.Formatter` for the access logger, the
`%(client_addr)s`, `%(request_line)s`, and `%(status_code)s` placeholders
are **not** available. The access log line will be formatted using only the
standard `%(message)s` field.
uvicorn-0.53.0/docs/concepts/websockets.md 0000664 0000000 0000000 00000010234 15251720332 0020525 0 ustar 00root root 0000000 0000000 **Uvicorn** supports the WebSocket protocol as defined in [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455).
## Upgrade Process
The WebSocket protocol starts as an HTTP connection that gets "upgraded" to a WebSocket connection
through a handshake process. Here's how it works:
```mermaid
sequenceDiagram
participant Client
participant Server
participant ASGI App
Note over Client,ASGI App: WebSocket Handshake Process
Client->>Server: HTTP GET Request
Note right of Client: Headers: Upgrade: websocket Connection: Upgrade Sec-WebSocket-Key: [key] Sec-WebSocket-Version: 13
Server->>ASGI App: websocket.connect event
Note right of Server: Scope type: "websocket"
alt Connection Accepted
ASGI App->>Server: {"type": "websocket.accept"}
Server->>Client: HTTP 101 Switching Protocols
Note right of Server: Headers: Upgrade: websocket Connection: Upgrade Sec-WebSocket-Accept: [hash]
Note over Client,ASGI App: WebSocket Connection Established
loop Message Exchange
Client->>Server: WebSocket Frame
Server->>ASGI App: websocket.receive event
ASGI App->>Server: {"type": "websocket.send", "text": "..."}
Server->>Client: WebSocket Frame
end
alt Client Closes
Client->>Server: Close Frame
Server->>ASGI App: websocket.disconnect event
else Server Closes
ASGI App->>Server: {"type": "websocket.close"}
Server->>Client: Close Frame
end
else Connection Rejected
ASGI App->>Server: {"type": "websocket.http.response.start", "status": 403}
Server->>Client: HTTP 403 Forbidden
end
```
1. **Initial HTTP Request**: The client sends a regular HTTP GET request with special headers indicating it wants to upgrade to WebSocket:
- `Upgrade: websocket`
- `Connection: Upgrade`
- `Sec-WebSocket-Key`: A base64-encoded random key
- `Sec-WebSocket-Version: 13`
2. **Server Processing**: Uvicorn receives the request and creates a WebSocket scope, sending a `websocket.connect` event to the ASGI application.
3. **Application Decision**: The ASGI app decides whether to accept or reject the connection based on authentication, authorization, or other logic.
4. **Handshake Completion**: If accepted, the server responds with HTTP 101 status and the computed `Sec-WebSocket-Accept` header.
5. **Full-Duplex Communication**: Once upgraded, both client and server can send messages at any time using WebSocket frames.
6. **Connection Termination**: Either side can initiate closing the connection with a close frame.
## ASGI WebSocket Events
**Uvicorn** translates WebSocket protocol messages into ASGI events:
- `websocket.connect`: Sent when a client requests a WebSocket upgrade
- `websocket.receive`: Sent when a message is received from the client
- `websocket.disconnect`: Sent when the connection is closed
The ASGI app can respond with:
- `websocket.accept`: Accept the connection upgrade with an optional subprotocol
- `websocket.send`: Send a message to the client
- `websocket.close`: Close the connection with an optional status code
You can read more about it on the [ASGI documentation](https://asgi.readthedocs.io/en/latest/specs/www.html#websocket).
## Protocol Implementations
**Uvicorn** has three implementations of the WebSocket protocol.
### WSProto Protocol
This implementation was the first implemented. It uses the
[`wsproto`](https://python-hyper.org/projects/wsproto/en/stable/) package underneath.
You can choose this protocol by setting the `--ws` option to `wsproto`.
### WebSocket Protocol
This implementation uses the [`websockets`](https://websockets.readthedocs.io/) package as dependency.
By default, if you have `websockets` installed, Uvicorn will use this protocol.
### WebSockets SansIO Protocol
Since `websockets` deprecated the API Uvicorn uses to run the previous protocol, we had to create this new
protocol that uses the `websockets` SansIO API.
You can choose this protocol by setting the `--ws` option to `websockets-sansio`.
!!! note
The SansIO implementation was released in Uvicorn version 0.35.0 in June 2025.
uvicorn-0.53.0/docs/contributing.md 0000664 0000000 0000000 00000013356 15251720332 0017255 0 ustar 00root root 0000000 0000000 # Contributing
Thank you for being interested in contributing to Uvicorn.
There are many ways you can contribute to the project:
- Using Uvicorn on your stack and [reporting bugs/issues you find](https://github.com/Kludex/uvicorn/issues/new)
- [Implementing new features and fixing bugs](https://github.com/Kludex/uvicorn/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
- [Review Pull Requests of others](https://github.com/Kludex/uvicorn/pulls)
- Write documentation
- Participate in discussions
## Reporting Bugs, Issues or Feature Requests
Found something that Uvicorn should support?
Stumbled upon some unexpected behaviour?
Need a missing functionality?
Contributions should generally start out from a previous discussion.
You can reach out someone at the [community chat](https://discord.com/invite/SWU73HffbV)
or at the [github discussions tab](https://github.com/Kludex/uvicorn/discussions).
When creating a new topic in the discussions tab, possible bugs may be raised
as a "Potential Issue" discussion, feature requests may be raised as an
"Ideas" discussion. We can then determine if the discussion needs
to be escalated into an "Issue" or not, or if we'd consider a pull request.
Try to be more descriptive as you can and in case of a bug report,
provide as much information as possible like:
- OS platform
- Python version
- Installed dependencies and versions (`python -m pip freeze`)
- Code snippet
- Error traceback
You should always try to reduce any examples to the *simplest possible case*
that demonstrates the issue.
Some possibly useful tips for narrowing down potential issues...
- Does the issue exist with a specific supervisor like `Multiprocess` or more than one?
- Does the issue exist on asgi, or wsgi, or both?
- Are you running Uvicorn in conjunction with Gunicorn, others, or standalone?
## Development
To start developing Uvicorn create a **fork** of the
[Uvicorn repository](https://github.com/Kludex/uvicorn) on GitHub.
Then clone your fork with the following command replacing `YOUR-USERNAME` with
your GitHub username:
```shell
$ git clone https://github.com/YOUR-USERNAME/uvicorn
```
You can now install the project and its dependencies using:
```shell
$ cd uvicorn
$ scripts/install
```
## Testing and Linting
We use custom shell scripts to automate testing, linting,
and documentation building workflow.
To run the tests, use:
```shell
$ scripts/test
```
Any additional arguments will be passed to `pytest`. See the [pytest documentation](https://docs.pytest.org/en/latest/how-to/usage.html) for more information.
For example, to run a single test script:
```shell
$ scripts/test tests/test_cli.py
```
To run the code auto-formatting:
```shell
$ scripts/lint
```
Lastly, to run code checks separately (they are also run as part of `scripts/test`), run:
```shell
$ scripts/check
```
## Documenting
Documentation pages are located under the `docs/` folder.
To run the documentation site locally (useful for previewing changes), use:
```shell
$ scripts/docs serve
```
## Resolving Build / CI Failures
Once you've submitted your pull request, the test suite will
automatically run, and the results will show up in GitHub.
If the test suite fails, you'll want to click through to the
"Details" link, and try to identify why the test suite failed.
Here are some common ways the test suite can fail:
### Check Job Failed
---
**Documentation**: [https://uvicorn.dev](https://uvicorn.dev)
**Source Code**: [https://www.github.com/Kludex/uvicorn](https://www.github.com/Kludex/uvicorn)
---
**Uvicorn** is an [ASGI](concepts/asgi.md) web server implementation for Python.
Until recently Python has lacked a minimal low-level server/application interface for
async frameworks. The [ASGI specification](https://asgi.readthedocs.io/en/latest/) 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**, **HTTP/2** and **WebSockets**.
## Sponsorship
Help us keep Uvicorn maintained and sustainable by [becoming a sponsor](https://github.com/sponsors/Kludex).
**Current sponsors:**
## Quickstart
**Uvicorn** is available on [PyPI](https://pypi.org/project/uvicorn/) so installation is as simple as:
=== "pip"
```bash
pip install uvicorn
```
=== "uv"
```bash
uv add uvicorn
```
See the [installation documentation](installation.md) for more information.
---
Let's create a simple ASGI application to run with Uvicorn:
```python title="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:
```shell
uvicorn main:app
```
---
## Usage
The uvicorn command line tool is the easiest way to run your application.
### Command line options
Run `uvicorn --help` to see the full set of command line options.
For more information, see the [settings documentation](settings.md).
### 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()`:
```py title="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`:
```py title="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:
```py title="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`](https://github.com/Kludex/uvicorn-worker) package instead.
```bash
python -m pip install uvicorn-worker
```
[Gunicorn](https://gunicorn.org/) 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](https://pypy.org/) compatible configuration use `uvicorn.workers.UvicornH11Worker`.
For more information, see the [deployment documentation](deployment/index.md).
### 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.
```py title="main.py"
def create_app():
app = ...
return app
```
```shell
uvicorn --factory main:create_app
```
uvicorn-0.53.0/docs/installation.md 0000664 0000000 0000000 00000004720 15251720332 0017242 0 ustar 00root root 0000000 0000000 **Uvicorn** is available on [PyPI](https://pypi.org/project/uvicorn/) so installation is as simple as:
=== "pip"
```bash
pip install uvicorn
```
=== "uv"
```bash
uv add uvicorn
```
The above will install Uvicorn with the minimal set of dependencies:
- [`h11`](https://github.com/python-hyper/h11) β Pure Python sans-io HTTP/1.1 implementation.
- [`click`](https://github.com/pallets/click) β Command line interface library.
If you are running on Python 3.10 or early versions,
[`typing_extensions`](https://github.com/python/typing_extensions) will also be installed.
## Optional Dependencies
There are many optional dependencies that can be installed to add support for various features.
If you just want to install all of them at once, you can use the `standard` extra:
=== "pip"
```bash
pip install 'uvicorn[standard]'
```
=== "uv"
```bash
uv add 'uvicorn[standard]'
```
The `standard` extra installs the following dependencies:
- **[`uvloop`](https://github.com/MagicStack/uvloop) β Fast, drop-in replacement of the built-in asyncio event loop.**
When `uvloop` is installed, Uvicorn will use it by default.
- **[`httptools`](https://github.com/MagicStack/httptools) β Python binding for the Node.js HTTP parser.**
When `httptools` is installed, Uvicorn will use it by default for HTTP/1.1 parsing.
You can read this issue to understand how it compares with `h11`: [h11/issues/9](https://github.com/python-hyper/h11/issues/9).
- **[`websockets`](https://websockets.readthedocs.io/en/stable/) β WebSocket library for Python.**
When `websockets` is installed, Uvicorn will use it by default for WebSocket handling.
You can alternatively install **[`wsproto`](https://github.com/python-hyper/wsproto)** and set the `--ws`
option to `wsproto` to use it instead.
- **[`watchfiles`](https://github.com/samuelcolvin/watchfiles) β Simple, modern and high performance file
watching and code reload in python.**
When `watchfiles` is installed, Uvicorn will use it by default for the `--reload` option.
- **[`python-dotenv`](https://github.com/theskumar/python-dotenv) β Reads key-value pairs from a `.env` file
and adds them to the environment.**
This is installed to allow you to use the `--env-file` option.
- **[`PyYAML`](https://github.com/yaml/pyyaml) β YAML parser and emitter for Python.**
This is installed to allow you to provide a `.yaml` file to the `--log-config` option.
uvicorn-0.53.0/docs/overrides/ 0000775 0000000 0000000 00000000000 15251720332 0016216 5 ustar 00root root 0000000 0000000 uvicorn-0.53.0/docs/overrides/main.html 0000664 0000000 0000000 00000000630 15251720332 0020027 0 ustar 00root root 0000000 0000000 {% extends "base.html" %}
{% block extrahead %}
{{ super() }}
{% endblock %}
uvicorn-0.53.0/docs/overrides/partials/ 0000775 0000000 0000000 00000000000 15251720332 0020035 5 ustar 00root root 0000000 0000000 uvicorn-0.53.0/docs/overrides/partials/nav.html 0000664 0000000 0000000 00000002607 15251720332 0021514 0 ustar 00root root 0000000 0000000 {% import "partials/nav-item.html" as item with context %}
{% set class = "md-nav md-nav--primary" %}
{% if "navigation.tabs" in features %}
{% set class = class ~ " md-nav--lifted" %}
{% endif %}
{% if "toc.integrate" in features %}
{% set class = class ~ " md-nav--integrated" %}
{% endif %}
uvicorn-0.53.0/docs/release-notes.md 0000664 0000000 0000000 00000065413 15251720332 0017315 0 ustar 00root root 0000000 0000000 ---
toc_depth: 2
---
## 0.53.0 (September 14, 2026)
This release adds experimental HTTP/2 support through `zttp`. Enable it with `--http zttp --http2`.
Upgrade-based h2c and WebSockets over HTTP/2 are not supported.
### Added
* Add experimental HTTP/2 support through `zttp` ([#2982](https://github.com/Kludex/uvicorn/pull/2982), [#3101](https://github.com/Kludex/uvicorn/pull/3101))
* Add support for `zuvloop` ([#3104](https://github.com/Kludex/uvicorn/pull/3104))
### Fixed
* Handle comma-separated, case-insensitive `Connection: close` tokens across HTTP implementations ([#3103](https://github.com/Kludex/uvicorn/pull/3103))
* Trust IPv6 loopback in the default `FORWARDED_ALLOW_IPS` value ([#3119](https://github.com/Kludex/uvicorn/pull/3119))
* Cancel the HTTP keep-alive timer when upgrading to WebSocket ([#3107](https://github.com/Kludex/uvicorn/pull/3107))
## 0.52.4 (August 18, 2026)
### Fixed
* Remove duplicate `Date` headers from accepted WebSocket handshakes with `websockets-sansio` ([#3078](https://github.com/Kludex/uvicorn/pull/3078))
## 0.52.3 (August 13, 2026)
### Changed
* Update `zttp` to 0.0.24 and use its combined receive path, improving HTTP/1.1 request parsing performance (#3067)
## 0.52.2 (August 13, 2026)
### Fixed
* Update `zttp` to 0.0.22, fixing bodyless request receives and improving HTTP/1 request parsing performance (#3063)
## 0.52.1 (August 1, 2026)
### Fixed
* Complete the closing handshake on server-initiated WebSocket closes in the `websockets-sansio` and `wsproto` implementations, waiting for the client's close reply with a 10 second timeout instead of resetting the connection (#3053)
* Add missing write flow control to the `websockets-sansio` implementation, preventing data truncation on server-initiated closes with large in-flight payloads (#3048)
* Handle connection loss while a WebSocket write is waiting on backpressure (#3050)
* Remove duplicate `Content-Type` and `Content-Length` headers from WebSocket denial responses on the `websockets-sansio` implementation, and deliver non-UTF-8 denial bodies intact (#3041)
## 0.52.0 (July 29, 2026)
This release adds an experimental HTTP/1.1 implementation backed by [zttp](https://zttp.marcelotryle.com/), a sans-IO HTTP parser I've been developing on the side: a core written in Zig, with bindings to Python. It has been running under a fuzzer for some weeks now, and has been through multiple rounds of security auditing.
It is still **experimental**, so don't put it in front of production traffic yet. Try it with `--http zttp`, and please send any feedback to the [issue tracker](https://github.com/Kludex/uvicorn/issues).
### Added
* Add an experimental `zttp` HTTP/1.1 implementation, selectable with `--http zttp` (#2979)
### Fixed
* Keep non-ASCII WebSocket request headers intact with websockets 17.0, which encodes them with ISO-8859-1 (#3036)
## 0.51.0 (July 8, 2026)
### Added
* Restart workers one at a time on `SIGHUP`, bringing each replacement up before retiring the old worker, so reloads no longer drop requests (#3025)
### Removed
* Remove `colorama` from the `standard` extra (#3027)
## 0.50.2 (July 6, 2026)
### Fixed
* Require `websockets>=13.0`, which the default `websockets-sansio` implementation needs (#3021)
## 0.50.1 (July 6, 2026)
### Fixed
* Split comma-separated `Sec-WebSocket-Protocol` values in the `websockets-sansio` implementation (#3019)
## 0.50.0 (July 4, 2026)
If you use WebSockets, note that `--ws auto` now picks the `websockets-sansio` implementation. You shouldn't need it, but you can pin `--ws websockets` to get the deprecated legacy one back.
### Changed
* Exit with the dedicated code 3 on any startup failure: app loading, socket bind and lifespan startup errors previously exited with a mix of 0, 1 and 3 (#3001)
* Stop the multiprocess supervisor when a worker exits with code 3 instead of restarting it forever (#3001)
* Default `--ws auto` to `websockets-sansio` when websockets is installed (#2985)
* Skip the eager app import in the parent process with `--reload` or `--workers`, fixing a memory regression introduced in 0.47.0 (#3012)
* Build a fresh `asgi` scope dict per request (#2977)
* Cache the `asgi` scope sub-dict per connection (#2976)
* Avoid copying single-frame WebSocket payloads in `websockets-sansio` (#2983)
* Memoize trusted host checks in `ProxyHeadersMiddleware` (#2970)
* Replace `click.style` with an internal ANSI style helper (#2981)
### Deprecated
* Deprecate the legacy `websockets` implementation; use `websockets-sansio` or `wsproto` instead (#2985)
## 0.49.0 (June 3, 2026)
### Changed
* Bump `httptools` minimum version to 0.8.0 (#2962)
* Consume duplicate forwarding headers in `ProxyHeadersMiddleware` (reverses the 0.48.0 behavior of ignoring them) (#2971)
## 0.48.0 (May 24, 2026)
### Changed
* Default `ssl_ciphers` to `None` and use OpenSSL defaults (#2940)
### Fixed
* Ignore duplicate forwarding headers in `ProxyHeadersMiddleware` (#2944)
## 0.47.0 (May 14, 2026)
### Added
* Add `ssl_context_factory` for custom `SSLContext` configuration (#2920)
### Changed
* Eagerly import the ASGI app in the parent process (#2919)
### Fixed
* Treat `fd=0` as a valid file descriptor with reload/workers (#2927)
## 0.46.0 (April 23, 2026)
### Added
* Support `ws_max_size` in `wsproto` implementation (#2915)
* Support `ws_ping_interval` and `ws_ping_timeout` in `wsproto` implementation (#2916)
### Changed
* Use `bytearray` for incoming WebSocket message buffer in `websockets-sansio` (#2917)
## 0.45.0 (April 21, 2026)
### Added
* Add `--reset-contextvars` flag to isolate ASGI request context (#2912)
* Accept `os.PathLike` for `log_config` (#2905)
* Accept `log_level` strings case-insensitively (#2907)
### Changed
* Revert "Emit `http.disconnect` on server shutdown for streaming responses" (#2913)
* Revert "Explicitly start ASGI run with empty context" (#2911)
### Fixed
* Preserve forwarded client ports in proxy headers middleware (#2903)
* Raise helpful `ImportError` when PyYAML is missing for YAML log config (#2906)
## 0.44.0 (April 6, 2026)
### Added
* Implement websocket keepalive pings for websockets-sansio (#2888)
## 0.43.0 (April 3, 2026)
You can quit Uvicorn now. We heard you, @pamelafox - all 47 of your Ctrl+C's (thanks for flagging it, and thanks to @tiangolo for the fix π). [See the tweet](https://x.com/pamelafox/status/2039097686155227623).
### Changed
* Emit `http.disconnect` ASGI `receive()` event on server shutting down for streaming responses (#2829)
* Use native `context` parameter for `create_task` on Python 3.11+ (#2859)
* Drop cast in ASGI types (#2875)
## 0.42.0 (March 16, 2026)
### Changed
* Use `bytearray` for request body accumulation to avoid O(n^2) allocation on fragmented bodies (#2845)
### Fixed
* Escape brackets and backslash in httptools `HEADER_RE` regex (#2824)
* Fix multiple issues in websockets sans-io implementation (#2825)
## 0.41.0 (February 16, 2026)
### Added
* Add `--limit-max-requests-jitter` to stagger worker restarts (#2707)
* Add socket path to `scope["server"]` (#2561)
### Changed
* Rename `LifespanOn.error_occured` to `error_occurred` (#2776)
### Fixed
* Ignore permission denied errors in watchfiles reloader (#2817)
* Ensure lifespan shutdown runs when `should_exit` is set during startup (#2812)
* Reduce the log level of 'request limit exceeded' messages (#2788)
## 0.40.0 (December 21, 2025)
### Remove
* Drop support for Python 3.9 (#2772)
## 0.39.0 (December 21, 2025)
### Fixed
* Send close frame on ASGI return for WebSockets (#2769)
* Explicitly start ASGI run with empty context (#2742)
## 0.38.0 (October 18, 2025)
### Added
* Support Python 3.14 (#2723)
## 0.37.0 (September 23, 2025)
### Added
* Add `--timeout-worker-healthcheck` option (#2711)
* Add `os.PathLike[str]` type to `ssl_ca_certs` (#2676)
## 0.36.1 (September 23, 2025)
### Fixed
* Raise an exception when calling removed `Config.setup_event_loop()` (#2709)
## 0.36.0 (September 20, 2025)
### Added
* Support custom IOLOOPs (#2435)
* Allow to provide importable string in `--http`, `--ws` and `--loop` (#2658)
## 0.35.0 (June 28, 2025)
### Added
* Add `WebSocketsSansIOProtocol` (#2540)
### Changed
* Refine help message for option `--proxy-headers` (#2653)
## 0.34.3 (June 1, 2025)
### Fixed
* Don't include `cwd()` when non-empty `--reload-dirs` is passed (#2598)
* Apply `get_client_addr` formatting to WebSocket logging (#2636)
## 0.34.2 (April 19, 2025)
### Fixed
* Flush stdout buffer on Windows to trigger reload (#2604)
## 0.34.1 (April 13, 2025)
### Deprecated
* Deprecate `ServerState` in the main module (#2581)
## 0.34.0 (December 15, 2024)
### Added
* Add `content-length` to 500 response in `wsproto` implementation (#2542)
### Removed
* Drop support for Python 3.8 (#2543)
## 0.33.0 (December 14, 2024)
### Removed
* Remove `WatchGod` support for `--reload` (#2536)
## 0.32.1 (November 20, 2024)
### Fixed
* Drop ASGI spec version to 2.3 on HTTP scope (#2513)
* Enable httptools lenient data on `httptools >= 0.6.3` (#2488)
## 0.32.0 (October 15, 2024)
### Added
* Officially support Python 3.13 (#2482)
* Warn when `max_request_limit` is exceeded (#2430)
## 0.31.1 (October 9, 2024)
### Fixed
* Support WebSockets 0.13.1 (#2471)
* Restore support for `[*]` in trusted hosts (#2480)
* Add `PathLike[str]` type hint for `ssl_keyfile` (#2481)
## 0.31.0 (September 27, 2024)
### Added
Improve `ProxyHeadersMiddleware` (#2468) and (#2231):
- Fix the host for requests from clients running on the proxy server itself.
- Fallback to host that was already set for empty x-forwarded-for headers.
- Also allow to specify IP Networks as trusted hosts. This greatly simplifies deployments
on docker swarm/kubernetes, where the reverse proxy might have a dynamic IP.
- This includes support for IPv6 Address/Networks.
## 0.30.6 (August 13, 2024)
### Fixed
- Don't warn when upgrade is not WebSocket and dependencies are installed (#2360)
## 0.30.5 (August 2, 2024)
### Fixed
- Don't close connection before receiving body on H11 (#2408)
## 0.30.4 (July 31, 2024)
### Fixed
- Close connection when `h11` sets client state to `MUST_CLOSE` (#2375)
## 0.30.3 (July 20, 2024)
### Fixed
- Suppress `KeyboardInterrupt` from CLI and programmatic usage (#2384)
- `ClientDisconnect` inherits from `OSError` instead of `IOError` (#2393)
## 0.30.2 (July 20, 2024)
### Added
- Add `reason` support to [`websocket.disconnect`](https://asgi.readthedocs.io/en/latest/specs/www.html#disconnect-receive-event-ws) event (#2324)
### Fixed
- Iterate subprocesses in-place on the process manager (#2373)
## 0.30.1 (June 2, 2024)
### Fixed
- Allow horizontal tabs `\t` in response header values (#2345)
## 0.30.0 (May 28, 2024)
### Added
- New multiprocess manager (#2183)
- Allow `ConfigParser` or a `io.IO[Any]` on `log_config` (#1976)
### Fixed
- Suppress side-effects of signal propagation (#2317)
- Send `content-length` header on 5xx (#2304)
### Deprecated
- Deprecate the `uvicorn.workers` module (#2302)
## 0.29.0 (March 19, 2024)
### Added
- Cooperative signal handling (#1600)
## 0.28.1 (March 19, 2024)
### Fixed
- Revert raise `ClientDisconnected` on HTTP (#2276)
## 0.28.0 (March 9, 2024)
### Added
- Raise `ClientDisconnected` on `send()` when client disconnected (#2220)
### Fixed
- Except `AttributeError` on `sys.stdin.fileno()` for Windows IIS10 (#1947)
- Use `X-Forwarded-Proto` for WebSockets scheme when the proxy provides it (#2258)
## 0.27.1 (February 10, 2024)
- Fix spurious LocalProtocolError errors when processing pipelined requests (#2243)
## 0.27.0.post1 (January 29, 2024)
### Fixed
- Fix nav overrides for newer version of Mkdocs Material (#2233)
## 0.27.0 (January 22, 2024)
### Added
- Raise `ClientDisconnect(IOError)` on `send()` when client disconnected (#2218)
- Bump ASGI WebSocket spec version to 2.4 (#2221)
## 0.26.0 (January 16, 2024)
### Changed
- Update `--root-path` to include the root path prefix in the full ASGI `path` as per the ASGI spec (#2213)
- Use `__future__.annotations` on some internal modules (#2199)
## 0.25.0 (December 17, 2023)
### Added
- Support the WebSocket Denial Response ASGI extension (#1916)
### Fixed
- Allow explicit hidden file paths on `--reload-include` (#2176)
- Properly annotate `uvicorn.run()` (#2158)
## 0.24.0.post1 (November 6, 2023)
### Fixed
- Revert mkdocs-material from 9.1.21 to 9.2.6 (#2148)
## 0.24.0 (November 4, 2023)
### Added
- Support Python 3.12 (#2145)
- Allow setting `app` via environment variable `UVICORN_APP` (#2106)
## 0.23.2 (July 31, 2023)
### Fixed
- Maintain the same behavior of `websockets` from 10.4 on 11.0 (#2061)
## 0.23.1 (July 18, 2023)
### Fixed
- Add `typing_extensions` for Python 3.10 and lower (#2053)
## 0.23.0 (July 10, 2023)
### Added
- Add `--ws-max-queue` parameter WebSockets (#2033)
### Removed
- Drop support for Python 3.7 (#1996)
- Remove `asgiref` as typing dependency (#1999)
### Fixed
- Set `scope["scheme"]` to `ws` or `wss` instead of `http` or `https` on `ProxyHeadersMiddleware` for WebSockets (#2043)
### Changed
- Raise `ImportError` on circular import (#2040)
- Use `logger.getEffectiveLevel()` instead of `logger.level` to check if log level is `TRACE` (#1966)
## 0.22.0 (April 28, 2023)
### Added
- Add `--timeout-graceful-shutdown` parameter (#1950)
- Handle `SIGBREAK` on Windows (#1909)
### Fixed
- Shutdown event is now being triggered on Windows when using hot reload (#1584)
- `--reload-delay` is effectively used on the `watchfiles` reloader (#1930)
## 0.21.1 (March 16, 2023)
### Fixed
- Reset lifespan state on each request (#1903)
## 0.21.0 (March 9, 2023)
### Added
- Introduce lifespan state (#1818)
- Allow headers to be sent as iterables on H11 implementation (#1782)
- Improve discoverability when --port=0 is used (#1890)
### Changed
- Avoid importing `h11` and `pyyaml` when not needed to improve import time (#1846)
- Replace current native `WSGIMiddleware` implementation by `a2wsgi` (#1825)
- Change default `--app-dir` from "." (dot) to "" (empty string) (#1835)
### Fixed
- Send code 1012 on shutdown for WebSockets (#1816)
- Use `surrogateescape` to encode headers on `websockets` implementation (#1005)
- Fix warning message on reload failure (#1784)
## 0.20.0 (November 20, 2022)
### Added
- Check if handshake is completed before sending frame on `wsproto` shutdown (#1737)
- Add default headers to WebSockets implementations (#1606 & #1747)
- Warn user when `reload` and `workers` flag are used together (#1731)
### Fixed
- Use correct `WebSocket` error codes on `close` (#1753)
- Send disconnect event on connection lost for `wsproto` (#996)
- Add `SIGQUIT` handler to `UvicornWorker` (#1710)
- Fix crash on exist with "--uds" if socket doesn't exist (#1725)
- Annotate `CONFIG_KWARGS` in `UvicornWorker` class (#1746)
### Removed
- Remove conditional on `RemoteProtocolError.event_hint` on `wsproto` (#1486)
- Remove unused `handle_no_connect` on `wsproto` implementation (#1759)
## 0.19.0 (October 19, 2022)
### Added
- Support Python 3.11 (#1652)
- Bump minimal `httptools` version to `0.5.0` (#1645)
- Ignore HTTP/2 upgrade and optionally ignore WebSocket upgrade (#1661)
- Add `py.typed` to comply with PEP 561 (#1687)
### Fixed
- Set `propagate` to `False` on "uvicorn" logger (#1288)
- USR1 signal is now handled correctly on `UvicornWorker`. (#1565)
- Use path with query string on `WebSockets` logs (#1385)
- Fix behavior on which "Date" headers were not updated on the same connection (#1706)
### Removed
- Remove the `--debug` flag (#1640)
- Remove the `DebugMiddleware` (#1697)
## 0.18.3 (August 24, 2022)
### Fixed
- Remove cyclic references on HTTP implementations. (#1604)
### Changed
- `reload_delay` default changed from `None` to `0.25` on `uvicorn.run()` and `Config`. `None` is not an acceptable value anymore. (#1545)
## 0.18.2 (June 27, 2022)
### Fixed
- Add default `log_config` on `uvicorn.run()` (#1541)
- Revert `logging` file name modification (#1543)
## 0.18.1 (June 23, 2022)
### Fixed
- Use `DEFAULT_MAX_INCOMPLETE_EVENT_SIZE` as default to `h11_max_incomplete_event_size` on the CLI (#1534)
## 0.18.0 (June 23, 2022)
### Added
- The `reload` flag prioritizes `watchfiles` instead of the deprecated `watchgod` (#1437)
- Annotate `uvicorn.run()` function (#1423)
- Allow configuring `max_incomplete_event_size` for `h11` implementation (#1514)
### Removed
- Remove `asgiref` dependency (#1532)
### Fixed
- Turn `raw_path` into bytes on both websockets implementations (#1487)
- Revert log exception traceback in case of invalid HTTP request (#1518)
- Set `asyncio.WindowsSelectorEventLoopPolicy()` when using multiple workers to avoid "WinError 87" (#1454)
## 0.17.6 (March 11, 2022)
### Changed
- Change `httptools` range to `>=0.4.0` (#1400)
## 0.17.5 (February 16, 2022)
### Fixed
- Fix case where url is fragmented in httptools protocol (#1263)
- Fix WSGI middleware not to explode quadratically in the case of a larger body (#1329)
### Changed
- Send HTTP 400 response for invalid request (#1352)
## 0.17.4 (February 4, 2022)
### Fixed
- Replace `create_server` by `create_unix_server` (#1362)
## 0.17.3 (February 3, 2022)
### Fixed
- Drop wsproto version checking. (#1359)
## 0.17.2 (February 3, 2022)
### Fixed
- Revert #1332. While trying to solve the memory leak, it introduced an issue (#1345) when the server receives big chunks of data using the `httptools` implementation. (#1354)
- Revert stream interface changes. This was introduced on 0.14.0, and caused an issue (#1226), which caused a memory leak when sending TCP pings. (#1355)
- Fix wsproto version check expression (#1342)
## 0.17.1 (January 28, 2022)
### Fixed
- Move all data handling logic to protocol and ensure connection is closed. (#1332)
- Change `spec_version` field from "2.1" to "2.3", as Uvicorn is compliant with that version of the ASGI specifications. (#1337)
## 0.17.0.post1 (January 24, 2022)
### Fixed
- Add the `python_requires` version specifier (#1328)
## 0.17.0 (January 14, 2022)
### Added
- Allow configurable websocket per-message-deflate setting (#1300)
- Support extra_headers for WS accept message (#1293)
- Add missing http version on websockets scope (#1309)
### Fixed/Removed
- Drop Python 3.6 support (#1261)
- Fix reload process behavior when exception is raised (#1313)
- Remove `root_path` from logs (#1294)
## 0.16.0 (December 8, 2021)
### Added
- Enable read of uvicorn settings from environment variables (#1279)
- Bump `websockets` to 10.0. (#1180)
- Ensure non-zero exit code when startup fails (#1278)
- Increase `httptools` version range from "==0.2.*" to ">=0.2.0,<0.4.0". (#1243)
- Override default asyncio event loop with reload only on Windows (#1257)
- Replace `HttpToolsProtocol.pipeline` type from `list` to `deque`. (#1213)
- Replace `WSGIResponder.send_queue` type from `list` to `deque`. (#1214)
### Fixed
- Main process exit after startup failure on reloader classes (#1177)
- Fix the need of `httptools` on minimal installation (#1135)
- Fix ping parameters annotation in Config class (#1127)
## 0.15.0 (August 13, 2021)
### Added
- Change reload to be configurable with glob patterns. Currently only `.py` files are watched, which is different from the previous default behavior. (#820)
- Add Python 3.10-rc.1 support. Now the server uses `asyncio.run` which will: start a fresh asyncio event loop, on shutdown cancel any background tasks rather than aborting them, `aexit` any remaining async generators, and shutdown the default `ThreadPoolExecutor`. (#1070)
- Exit with status 3 when worker starts failed (#1077)
- Add option to set websocket ping interval and timeout (#1048)
- Adapt bind_socket to make it usable with multiple processes (#1009)
- Add existence check to the reload directory(ies) (#1089)
- Add missing trace log for websocket protocols (#1083)
- Support disabling default Server and Date headers (#818)
### Changed
- Add PEP440 compliant version of click (#1099)
- Bump asgiref to 3.4.0 (#1100)
### Fixed
- When receiving a `SIGTERM` supervisors now terminate their processes before joining them (#1069)
- Fix `httptools` range to `>=0.4.0` (#1400)
## 0.14.0 (June 1, 2021)
### Added
- Defaults ws max_size on server to 16MB (#995)
- Improve user feedback if no ws library installed (#926 and #1023)
- Support 'reason' field in 'websocket.close' messages (#957)
- Implemented lifespan.shutdown.failed (#755)
### Changed
- Upgraded websockets requirements (#1065)
- Switch to asyncio streams API (#869)
- Update httptools from 0.1.* to 0.2.* (#1024)
- Allow Click 8.0, refs #1016 (#1042)
- Add search for a trusted host in ProxyHeadersMiddleware (#591)
- Up wsproto to 1.0.0 (#892)
### Fixed
- Force reload_dirs to be a list (#978)
- Fix gunicorn worker not running if extras not installed (#901)
- Fix socket port 0 (#975)
- Prevent garbage collection of main lifespan task (#972)
## 0.13.4 (February 20, 2021)
### Fixed
- Fixed wsgi middleware PATH_INFO encoding (#962)
- Fixed uvloop dependency (#952) then (#959)
- Relax watchgod up bound (#946)
- Return 'connection: close' header in response (#721)
### Added
- Docs: Nginx + websockets (#948)
- Document the default value of 1 for workers (#940) (#943)
- Enabled permessage-deflate extension in websockets (#764)
## 0.13.3 (December 29, 2020)
### Fixed
- Prevent swallowing of return codes from `subprocess` when running with Gunicorn by properly resetting signals. (#895)
- Tweak detection of app factories to be more robust. A warning is now logged when passing a factory without the `--factory` flag. (#914)
- Properly clean tasks when handshake is aborted when running with `--ws websockets`. (#921)
## 0.13.2 (December 12, 2020)
### Fixed
- Log full exception traceback in case of invalid HTTP request. (#886 and #888)
## 0.13.1 (December 12, 2020)
### Fixed
- Prevent exceptions when the ASGI application rejects a connection during the WebSocket handshake, when running on both `--ws wsproto` or `--ws websockets`. (#704 and #881)
- Ensure connection `scope` doesn't leak in logs when using JSON log formatters. (#859 and #884)
## 0.13.0 (December 8, 2020)
### Added
- Add `--factory` flag to support factory-style application imports. (#875)
- Skip installation of signal handlers when not in the main thread. Allows using `Server` in multithreaded contexts without having to override `.install_signal_handlers()`. (#871)
## 0.12.3 (November 21, 2020)
### Fixed
- Fix race condition that leads Quart to hang with uvicorn (#848)
- Use latin1 when decoding X-Forwarded-* headers (#701)
- Rework IPv6 support (#837)
- Cancel old keepalive-trigger before setting new one. (#832)
## 0.12.2 (October 19, 2020)
### Added
- Adding ability to decrypt ssl key file (#808)
- Support .yml log config files (#799)
- Added python 3.9 support (#804)
### Fixed
- Fixes watchgod with common prefixes (#817)
- Fix reload with ipv6 host (#803)
- Added cli support for headers containing colon (#813)
- Sharing socket across workers on windows (#802)
- Note the need to configure trusted "ips" when using unix sockets (#796)
## 0.12.1 (September 30, 2020)
### Changed
- Pinning h11 and python-dotenv to min versions (#789)
- Get docs/index.md in sync with README.md (#784)
### Fixed
- Improve changelog by pointing out breaking changes (#792)
## 0.12.0 (September 28, 2020)
### Added
- Make reload delay configurable (#774)
- Upgrade maximum h11 dependency version to 0.10 (#772)
- Allow .json or .yaml --log-config files (#665)
- Add ASGI dict to the lifespan scope (#754)
- Upgrade wsproto to 0.15.0 (#750)
- Use optional package installs (#666)
### Changed
- Don't set log level for root logger (#767) 8/28/20 df81b168
- Uvicorn no longer ships extra dependencies `uvloop`, `websockets` and `httptools` as default.
To install these dependencies use `uvicorn[standard]`.
### Fixed
- Revert "Improve shutdown robustness when using `--reload` or multiprocessing (#620)" (#756)
- Fix terminate error in windows (#744)
- Fix bug where --log-config disables uvicorn loggers (#512)
## 0.11.8 (July 30, 2020)
* Fix a regression that caused Uvicorn to crash when using `--interface=wsgi`. (#730)
* Fix a regression that caused Uvicorn to crash when using unix domain sockets. (#729)
## 0.11.7 (July 28, 2020)
* SECURITY FIX: Prevent sending invalid HTTP header names and values. (#725)
* SECURITY FIX: Ensure path value is escaped before logging to the console. (#724)
* Fix `--proxy-headers` client IP and host when using a Unix socket. (#636)
## 0.11.6 (July 17, 2020)
* Fix overriding the root logger.
## 0.11.5 (April 29, 2020)
* Revert "Watch all files, not just .py" due to unexpected side effects.
* Revert "Pass through gunicorn timeout config." due to unexpected side effects.
## 0.11.4 (April 28, 2020)
* Use `watchgod`, if installed, for watching code changes.
* Watch all files, not just .py.
* Pass through gunicorn timeout config.
## 0.11.3 (February 17, 2020)
* Update dependencies.
## 0.11.2 (January 20, 2020)
* Don't open socket until after application startup.
* Support `--backlog`.
## 0.11.1 (December 20, 2019)
* Use a more liberal `h11` dependency. Either `0.8.*` or `0.9.*``.
## 0.11.0 (December 20, 2019)
* Fix reload/multiprocessing on Windows with Python 3.8.
* Drop IOCP support. (Required for fix above.)
* Add `uvicorn --version` flag.
* Add `--use-colors` and `--no-use-colors` flags.
* Display port correctly, when auto port selection isused with `--port=0`.
## 0.10.8 (November 12, 2019)
* Fix reload/multiprocessing error.
## 0.10.7 (November 12, 2019)
* Use resource_sharer.DupSocket to resolve socket sharing on Windows.
## 0.10.6 (November 12, 2019)
* Exit if `workers` or `reload` are use without an app import string style.
* Reorganise supervisor processes to properly hand over sockets on windows.
## 0.10.5 (November 12, 2019)
* Update uvloop dependency to 0.14+
## 0.10.4 (November 9, 2019)
* Error clearly when `workers=