---
[](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 supports HTTP/1.1 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`.
- windows users will have `colorama` installed for the colored logs.
- `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.38.0/docs/ 0000775 0000000 0000000 00000000000 15074714634 0014232 5 ustar 00root root 0000000 0000000 uvicorn-0.38.0/docs/CNAME 0000664 0000000 0000000 00000000020 15074714634 0014770 0 ustar 00root root 0000000 0000000 www.uvicorn.org
uvicorn-0.38.0/docs/concepts/ 0000775 0000000 0000000 00000000000 15074714634 0016050 5 ustar 00root root 0000000 0000000 uvicorn-0.38.0/docs/concepts/asgi.md 0000664 0000000 0000000 00000017730 15074714634 0017325 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.38.0/docs/concepts/event-loop.md 0000664 0000000 0000000 00000005014 15074714634 0020462 0 ustar 00root root 0000000 0000000 # Event Loop
Uvicorn provides two 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 [`ProactorEventLoop`][asyncio.ProactorEventLoop] if running with multiple workers,
otherwise it uses the standard [`SelectorEventLoop`][asyncio.SelectorEventLoop] for better performance.
??? info "Why does `SelectorEventLoop` not work 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).
## 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.38.0/docs/concepts/lifespan.md 0000664 0000000 0000000 00000010234 15074714634 0020173 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.38.0/docs/concepts/websockets.md 0000664 0000000 0000000 00000010234 15074714634 0020543 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.38.0/docs/contributing.md 0000664 0000000 0000000 00000013356 15074714634 0017273 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** and **WebSockets**.
## 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
```bash
{{ uvicorn_help }}
```
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.38.0/docs/installation.md 0000664 0000000 0000000 00000005203 15074714634 0017255 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.
- **[`colorama`](https://github.com/tartley/colorama) β Cross-platform support for ANSI terminal
colors.**
This is installed only on Windows, to provide colored logs.
- **[`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.38.0/docs/overrides/ 0000775 0000000 0000000 00000000000 15074714634 0016234 5 ustar 00root root 0000000 0000000 uvicorn-0.38.0/docs/overrides/main.html 0000664 0000000 0000000 00000000630 15074714634 0020045 0 ustar 00root root 0000000 0000000 {% extends "base.html" %}
{% block extrahead %}
{{ super() }}
{% endblock %}
uvicorn-0.38.0/docs/overrides/partials/ 0000775 0000000 0000000 00000000000 15074714634 0020053 5 ustar 00root root 0000000 0000000 uvicorn-0.38.0/docs/overrides/partials/nav.html 0000664 0000000 0000000 00000002413 15074714634 0021525 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.38.0/docs/overrides/partials/toc-item.html 0000664 0000000 0000000 00000001217 15074714634 0022463 0 ustar 00root root 0000000 0000000
{{ toc_item.title }}
{% if toc_item.children %}
{% endif %}
uvicorn-0.38.0/docs/plugins/ 0000775 0000000 0000000 00000000000 15074714634 0015713 5 ustar 00root root 0000000 0000000 uvicorn-0.38.0/docs/plugins/main.py 0000664 0000000 0000000 00000002636 15074714634 0017220 0 ustar 00root root 0000000 0000000 from __future__ import annotations as _annotations
import re
import subprocess
from functools import lru_cache
from mkdocs.config import Config
from mkdocs.structure.files import Files
from mkdocs.structure.pages import Page
def on_page_content(html: str, page: Page, config: Config, files: Files) -> str:
"""Called on each page after the markdown is converted to HTML."""
html = add_hyperlink_to_pull_request(html, page, config, files)
return html
def add_hyperlink_to_pull_request(html: str, page: Page, config: Config, files: Files) -> str:
"""Add hyperlink on PRs mentioned on the release notes page.
If we find "(#\\d+)" it will be added an hyperlink to https://github.com/Kludex/uvicorn/pull/$1.
"""
if not page.file.name == "release-notes":
return html
return re.sub(r"\(#(\d+)\)", r"(#\1)", html)
def on_page_markdown(markdown: str, page: Page, config: Config, files: Files) -> str:
"""Called on each file after it is read and before it is converted to HTML."""
markdown = uvicorn_print_help(markdown, page)
return markdown
def uvicorn_print_help(markdown: str, page: Page) -> str:
return re.sub(r"{{ *uvicorn_help *}}", get_uvicorn_help(), markdown)
@lru_cache
def get_uvicorn_help():
output = subprocess.run(["uvicorn", "--help"], capture_output=True, check=True)
return output.stdout.decode()
uvicorn-0.38.0/docs/release-notes.md 0000664 0000000 0000000 00000046454 15074714634 0017337 0 ustar 00root root 0000000 0000000 ---
toc_depth: 2
---
## 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 depedencies 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=` is used with app instance, instead of an app import string.
* Switch `--reload-dir` to current working directory by default.
## 0.10.3 (November 1, 2019)
* Add ``--log-level trace`
## 0.10.2 (October 31, 2019)
* Enable --proxy-headers by default.
## 0.10.1 (October 31, 2019)
* Resolve issues with logging when using `--reload` or `--workers`.
* Setup up root logger to capture output for all logger instances, not just `uvicorn.error` and `uvicorn.access`.
## 0.10.0 (October 29, 2019)
* Support for Python 3.8
* Separated out `uvicorn.error` and `uvicorn.access` logs.
* Coloured log output when connected to a terminal.
* Dropped `logger=` config setting.
* Added `--log-config [FILE]` and `log_config=[str|dict]`. May either be a Python logging config dictionary or the file name of a logging configuration.
* Added `--forwarded_allow_ips` and `forwarded_allow_ips`. Defaults to the value of the `$FORWARDED_ALLOW_IPS` environment variable or "127.0.0.1". The `--proxy-headers` flag now defaults to `True`, but only trusted IPs are used to populate forwarding info.
* The `--workers` setting now defaults to the value of the `$WEB_CONCURRENCY` environment variable.
* Added support for `--env-file`. Requires `python-dotenv`.
uvicorn-0.38.0/docs/server-behavior.md 0000664 0000000 0000000 00000015162 15074714634 0017664 0 ustar 00root root 0000000 0000000 # Server Behavior
Uvicorn is designed with particular attention to connection and resource management, in order to provide a robust server implementation. It aims to ensure graceful behavior to either server or client errors, and resilience to poor client behavior or denial of service attacks.
## HTTP Headers
The `Server` and `Date` headers are added to all outgoing requests.
If a `Connection: Close` header is included then Uvicorn will close the connection after the response. Otherwise connections will stay open, pending the keep-alive timeout.
If a `Content-Length` header is included then Uvicorn will ensure that the content length of the response body matches the value in the header, and raise an error otherwise.
If no `Content-Length` header is included then Uvicorn will use chunked encoding for the response body, and will set a `Transfer-Encoding` header if required.
If a `Transfer-Encoding` header is included then any `Content-Length` header will be ignored.
HTTP headers are mandated to be case-insensitive. Uvicorn will always send response headers strictly in lowercase.
---
## Flow Control
Proper flow control ensures that large amounts of data do not become buffered on the transport when either side of a connection is sending data faster than its counterpart is able to handle.
### Write flow control
If the write buffer passes a high water mark, then Uvicorn ensures the ASGI `send` messages will only return once the write buffer has been drained below the low water mark.
### Read flow control
Uvicorn will pause reading from a transport once the buffered request body hits a high water mark, and will only resume once `receive` has been called, or once the response has been sent.
---
## Request and Response bodies
### Response completion
Once a response has been sent, Uvicorn will no longer buffer any remaining request body. Any later calls to `receive` will return an `http.disconnect` message.
Together with the read flow control, this behavior ensures that responses that return without reading the request body will not stream any substantial amounts of data into memory.
### Expect: 100-Continue
The `Expect: 100-Continue` header may be sent by clients to require a confirmation from the server before uploading the request body. This can be used to ensure that large request bodies are only sent once the client has confirmation that the server is willing to accept the request.
Uvicorn ensures that any required `100 Continue` confirmations are only sent if the ASGI application calls `receive` to read the request body.
Note that proxy configurations may not necessarily forward on `Expect: 100-Continue` headers. In particular, Nginx defaults to buffering request bodies, and automatically sends `100 Continues` rather than passing the header on to the upstream server.
### HEAD requests
Uvicorn will strip any response body from HTTP requests with the `HEAD` method.
Applications should generally treat `HEAD` requests in the same manner as `GET` requests, in order to ensure that identical headers are sent in both cases, and that any ASGI middleware that modifies the headers will operate identically in either case.
One exception to this might be if your application serves large file downloads, in which case you might wish to only generate the response headers.
---
## Timeouts
Uvicorn provides the following timeouts:
* Keep-Alive. Defaults to 5 seconds. Between requests, connections must receive new data within this period or be disconnected.
---
## Resource Limits
Uvicorn provides the following resource limiting:
* Concurrency. Defaults to `None`. If set, this provides a maximum number of concurrent tasks *or* open connections that should be allowed. Any new requests or connections that occur once this limit has been reached will result in a "503 Service Unavailable" response. Setting this value to a limit that you know your servers are able to support will help ensure reliable resource usage, even against significantly over-resourced servers.
* Max requests. Defaults to `None`. If set, this provides a maximum number of HTTP requests that will be serviced before terminating a process. Together with a process manager this can be used to prevent memory leaks from impacting long running processes.
---
## Server Errors
Server errors will be logged at the `error` log level. All logging defaults to being written to `stdout`.
### Exceptions
If an exception is raised by an ASGI application, and a response has not yet been sent on the connection, then a `500 Server Error` HTTP response will be sent.
Uvicorn sends the headers and the status code as soon as it receives from the ASGI application. This means that if the application sends a [Response Start](https://asgi.readthedocs.io/en/latest/specs/www.html#response-start-send-event)
message with a status code of `200 OK`, and then an exception is raised, the response will still be sent with a status code of `200 OK`.
### Invalid responses
Uvicorn will ensure that ASGI applications send the correct sequence of messages, and will raise errors otherwise. This includes checking for no response sent, partial response sent, or invalid message sequences being sent.
---
## Graceful Process Shutdown
Graceful process shutdowns are particularly important during a restart period. During this period you want to:
* Start a number of new server processes to handle incoming requests, listening on the existing socket.
* Stop the previous server processes from listening on the existing socket.
* Close any connections that are not currently waiting on an HTTP response, and wait for any other connections to finalize their HTTP responses.
* Wait for any background tasks to run to completion, such as occurs when the ASGI application has sent the HTTP response, but the asyncio task has not yet run to completion.
Uvicorn handles process shutdown gracefully, ensuring that connections are properly finalized, and all tasks have run to completion. During a shutdown period Uvicorn will ensure that responses and tasks must still complete within the configured timeout periods.
---
## HTTP Pipelining
HTTP/1.1 provides support for sending multiple requests on a single connection, before having received each corresponding response. Servers are required to support HTTP pipelining, but it is now generally accepted to lead to implementation issues. It is not enabled on browsers, and may not necessarily be enabled on any proxies that the HTTP request passes through.
Uvicorn supports pipelining pragmatically. It will queue up any pipelined HTTP requests, and pause reading from the underlying transport. It will not start processing pipelined requests until each response has been dealt with in turn.
uvicorn-0.38.0/docs/settings.md 0000664 0000000 0000000 00000025273 15074714634 0016425 0 ustar 00root root 0000000 0000000 # Settings
Use the following options to configure Uvicorn, when running from the command line.
## Configuration Methods
There are three ways to configure Uvicorn:
1. **Command Line**: Use command line options when running Uvicorn directly.
```bash
uvicorn main:app --host 0.0.0.0 --port 8000
```
2. **Programmatic**: Use keyword arguments when running programmatically with `uvicorn.run()`.
```python
uvicorn.run("main:app", host="0.0.0.0", port=8000)
```
!!! note
When using `reload=True` or `workers=NUM`, you should put `uvicorn.run` into
an `if __name__ == '__main__'` clause in the main module.
3. **Environment Variables**: Use environment variables with the prefix `UVICORN_`.
```bash
export UVICORN_HOST="0.0.0.0"
export UVICORN_PORT="8000"
uvicorn main:app
```
CLI options and the arguments for `uvicorn.run()` take precedence over environment variables.
Also note that `UVICORN_*` prefixed settings cannot be used from within an environment
configuration file. Using an environment configuration file with the `--env-file` flag is
intended for configuring the ASGI application that uvicorn runs, rather than configuring
uvicorn itself.
## Application
* `APP` - The ASGI application to run, in the format `":"`.
* `--factory` - Treat `APP` as an application factory, i.e. a `() -> ` callable.
* `--app-dir ` - Look for APP in the specified directory by adding it to the PYTHONPATH. **Default:** *Current working directory*.
## Socket Binding
* `--host ` - Bind socket to this host. Use `--host 0.0.0.0` to make the application available on your local network. IPv6 addresses are supported, for example: `--host '::'`. **Default:** *'127.0.0.1'*.
* `--port ` - Bind to a socket with this port. If set to 0, an available port will be picked. **Default:** *8000*.
* `--uds ` - Bind to a UNIX domain socket, for example `--uds /tmp/uvicorn.sock`. Useful if you want to run Uvicorn behind a reverse proxy.
* `--fd ` - Bind to socket from this file descriptor. Useful if you want to run Uvicorn within a process manager.
## Development
* `--reload` - Enable auto-reload. Uvicorn supports two versions of auto-reloading behavior enabled by this option. **Default:** *False*.
* `--reload-dir ` - Specify which directories to watch for python file changes. May be used multiple times. If unused, then by default the whole current directory will be watched. If you are running programmatically use `reload_dirs=[]` and pass a list of strings.
* `--reload-delay ` - Delay between previous and next check if application needs to be reloaded. **Default:** *0.25*.
### Reloading without watchfiles
If Uvicorn _cannot_ load [watchfiles](https://pypi.org/project/watchfiles/) at runtime, it will periodically look for changes in modification times to all `*.py` files (and only `*.py` files) inside of its monitored directories. See the `--reload-dir` option. Specifying other file extensions is not supported unless watchfiles is installed. See the `--reload-include` and `--reload-exclude` options for details.
### Reloading with watchfiles
For more nuanced control over which file modifications trigger reloads, install `uvicorn[standard]`, which includes watchfiles as a dependency. Alternatively, install [watchfiles](https://pypi.org/project/watchfiles/) where Uvicorn can see it.
Using Uvicorn with watchfiles will enable the following options (which are otherwise ignored):
* `--reload-include ` - Specify a glob pattern to match files or directories which will be watched. May be used multiple times. By default the following patterns are included: `*.py`. These defaults can be overwritten by including them in `--reload-exclude`.
* `--reload-exclude ` - Specify a glob pattern to match files or directories which will excluded from watching. May be used multiple times. By default the following patterns are excluded: `.*, .py[cod], .sw.*, ~*`. These defaults can be overwritten by including them in `--reload-include`.
!!! tip
When using Uvicorn through [WSL](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux), you might
have to set the `WATCHFILES_FORCE_POLLING` environment variable, for file changes to trigger a reload.
See [watchfiles documentation](https://watchfiles.helpmanual.io/api/watch/) for further details.
## Production
* `--workers ` - Number of worker processes. Defaults to the `$WEB_CONCURRENCY` environment variable if available, or 1. Not valid with `--reload`.
* `--env-file ` - Environment configuration file for the ASGI application. **Default:** *None*.
* `--timeout-worker-healthcheck ` - Maximum number of seconds to wait for a worker to respond to a healthcheck. **Default:** *5*.
!!! note
The `--reload` and `--workers` arguments are mutually exclusive. You cannot use both at the same time.
## Logging
* `--log-config ` - Logging configuration file. **Options:** *`dictConfig()` formats: .json, .yaml*. Any other format will be processed with `fileConfig()`. Set the `formatters.default.use_colors` and `formatters.access.use_colors` values to override the auto-detected behavior.
* If you wish to use a YAML file for your logging config, you will need to include PyYAML as a dependency for your project or install uvicorn with the `[standard]` optional extras.
* `--log-level ` - Set the log level. **Options:** *'critical', 'error', 'warning', 'info', 'debug', 'trace'.* **Default:** *'info'*.
* `--no-access-log` - Disable access log only, without changing log level.
* `--use-colors / --no-use-colors` - Enable / disable colorized formatting of the log records. If not set, colors will be auto-detected. This option is ignored if the `--log-config` CLI option is used.
## Implementation
* `--loop ` - Set the event loop implementation. The uvloop implementation provides greater performance, but is not compatible with Windows or PyPy. **Options:** *'auto', 'asyncio', 'uvloop'.* **Default:** *'auto'*.
* `--http ` - Set the HTTP protocol implementation. The httptools implementation provides greater performance, but it not compatible with PyPy. **Options:** *'auto', 'h11', 'httptools'.* **Default:** *'auto'*.
* `--ws ` - Set the WebSockets protocol implementation. Either of the `websockets` and `wsproto` packages are supported. There are two versions of `websockets` supported: `websockets` and `websockets-sansio`. Use `'none'` to ignore all websocket requests. **Options:** *'auto', 'none', 'websockets', 'websockets-sansio', 'wsproto'.* **Default:** *'auto'*.
* `--ws-max-size ` - Set the WebSockets max message size, in bytes. Only available with the `websockets` protocol. **Default:** *16777216* (16 MB).
* `--ws-max-queue ` - Set the maximum length of the WebSocket incoming message queue. Only available with the `websockets` protocol. **Default:** *32*.
* `--ws-ping-interval ` - Set the WebSockets ping interval, in seconds. Only available with the `websockets` protocol. **Default:** *20.0*.
* `--ws-ping-timeout ` - Set the WebSockets ping timeout, in seconds. Only available with the `websockets` protocol. **Default:** *20.0*.
* `--ws-per-message-deflate ` - Enable/disable WebSocket per-message-deflate compression. Only available with the `websockets` protocol. **Default:** *True*.
* `--lifespan ` - Set the Lifespan protocol implementation. **Options:** *'auto', 'on', 'off'.* **Default:** *'auto'*.
* `--h11-max-incomplete-event-size ` - Set the maximum number of bytes to buffer of an incomplete event. Only available for `h11` HTTP protocol implementation. **Default:** *16384* (16 KB).
## Application Interface
* `--interface ` - Select ASGI3, ASGI2, or WSGI as the application interface.
Note that WSGI mode always disables WebSocket support, as it is not supported by the WSGI interface.
**Options:** *'auto', 'asgi3', 'asgi2', 'wsgi'.* **Default:** *'auto'*.
!!! warning
Uvicorn's native WSGI implementation is deprecated, you should switch
to [a2wsgi](https://github.com/abersheeran/a2wsgi) (`pip install a2wsgi`).
## HTTP
* `--root-path ` - Set the ASGI `root_path` for applications submounted below a given URL path. **Default:** *""*.
* `--proxy-headers / --no-proxy-headers` - Enable/Disable X-Forwarded-Proto, X-Forwarded-For to populate remote address info. Defaults to enabled, but is restricted to only trusting connecting IPs in the `forwarded-allow-ips` configuration.
* `--forwarded-allow-ips ` - Comma separated list of IP Addresses, IP Networks, or literals (e.g. UNIX Socket path) to trust with proxy headers. Defaults to the `$FORWARDED_ALLOW_IPS` environment variable if available, or '127.0.0.1'. The literal `'*'` means trust everything.
* `--server-header / --no-server-header` - Enable/Disable default `Server` header. **Default:** *True*.
* `--date-header / --no-date-header` - Enable/Disable default `Date` header. **Default:** *True*.
* `--header ` - Specify custom default HTTP response headers as a Name:Value pair. May be used multiple times.
!!! note
The `--no-date-header` flag doesn't have effect on the `websockets` implementation.
## HTTPS
The [SSL context](https://docs.python.org/3/library/ssl.html#ssl.SSLContext) can be configured with the following options:
* `--ssl-keyfile ` - The SSL key file.
* `--ssl-keyfile-password ` - The password to decrypt the ssl key.
* `--ssl-certfile ` - The SSL certificate file.
* `--ssl-version ` - The SSL version to use. **Default:** *ssl.PROTOCOL_TLS_SERVER*.
* `--ssl-cert-reqs ` - Whether client certificate is required. **Default:** *ssl.CERT_NONE*.
* `--ssl-ca-certs ` - The CA certificates file.
* `--ssl-ciphers ` - The ciphers to use. **Default:** *"TLSv1"*.
To understand more about the SSL context options, please refer to the [Python documentation](https://docs.python.org/3/library/ssl.html).
## Resource Limits
* `--limit-concurrency ` - Maximum number of concurrent connections or tasks to allow, before issuing HTTP 503 responses. Useful for ensuring known memory usage patterns even under over-resourced loads.
* `--limit-max-requests ` - Maximum number of requests to service before terminating the process. Useful when running together with a process manager, for preventing memory leaks from impacting long-running processes.
* `--backlog ` - Maximum number of connections to hold in backlog. Relevant for heavy incoming traffic. **Default:** *2048*.
## Timeouts
* `--timeout-keep-alive ` - Close Keep-Alive connections if no new data is received within this timeout (in seconds). **Default:** *5*.
* `--timeout-graceful-shutdown ` - Maximum number of seconds to wait for graceful shutdown. After this timeout, the server will start terminating requests.
uvicorn-0.38.0/docs/sponsorship.md 0000664 0000000 0000000 00000026027 15074714634 0017152 0 ustar 00root root 0000000 0000000 # β¨ Sponsor Starlette & Uvicorn β¨
Thank you for your interest in sponsoring Starlette and Uvicorn! β€οΈ
Your support *directly* contributes to the ongoing development, maintenance, and long-term sustainability of both projects.
67M+
Starlette Downloads/Month
57M+
Uvicorn Downloads/Month
19K+
Combined GitHub Stars
## Why Sponsor?
While Starlette and Uvicorn are part of the [Encode](https://github.com/encode) organization,
they have been primarily maintained by [**Marcelo Trylesinski (Kludex)**](https://github.com/Kludex)
for the past several years. His dedication and consistent work have been instrumental in keeping
these projects robust, secure, and up-to-date.
This sponsorship page was created to give the community an opportunity to support Marcelo's continued
efforts in maintaining and improving both projects. Your sponsorship directly enables him to
dedicate more time and resources to maintaining and improving these essential tools:
- [x] **Active Development:** Developing new features, enhancing existing ones, and
keeping both projects aligned with the latest developments in the Python and ASGI ecosystems. π»
- [x] **Community Support:** Providing better support, addressing user issues,
and cultivating a welcoming environment for contributors. π€
- [x] **Long-Term Stability:** Ensuring the long-term viability of both projects through strategic
planning and addressing technical debt. π³
- [x] **Bug Fixes & Maintenance:** Providing prompt attention to bug reports and
general maintenance to keep the projects reliable. π¨
- [x] **Security:** Ensuring robust security practices, conducting regular security audits, and
promptly addressing vulnerabilities to protect millions of production deployments. π
- [x] **Documentation:** Creating comprehensive guides, tutorials, and examples to help users of all skill levels. π
## How Sponsorship Works
We currently manage sponsorships *exclusively* through **GitHub Sponsors**. This platform integrates seamlessly with the GitHub ecosystem, making it easy for organizations to contribute.
π Become a Sponsor Today! π
Your support helps keep Starlette and Uvicorn growing stronger!
We are currently evaluating whether to expand our sponsorship options beyond GitHub Sponsors. If your company would be interested in sponsoring Starlette and Uvicorn but prefers to use a different platform (e.g., Open Collective, direct invoicing), please let us know!
Your feedback is invaluable in helping us make sponsorship as accessible as possible. Share your thoughts by:
## Why Sponsor?
While Starlette and Uvicorn are part of the [Encode](https://github.com/encode) organization,
they have been primarily maintained by [**Marcelo Trylesinski (Kludex)**](https://github.com/Kludex)
for the past several years. His dedication and consistent work have been instrumental in keeping
these projects robust, secure, and up-to-date.
This sponsorship page was created to give the community an opportunity to support Marcelo's continued
efforts in maintaining and improving both projects. Your sponsorship directly enables him to
dedicate more time and resources to maintaining and improving these essential tools:
- [x] **Active Development:** Developing new features, enhancing existing ones, and
keeping both projects aligned with the latest developments in the Python and ASGI ecosystems. π»
- [x] **Community Support:** Providing better support, addressing user issues,
and cultivating a welcoming environment for contributors. π€
- [x] **Long-Term Stability:** Ensuring the long-term viability of both projects through strategic
planning and addressing technical debt. π³
- [x] **Bug Fixes & Maintenance:** Providing prompt attention to bug reports and
general maintenance to keep the projects reliable. π¨
- [x] **Security:** Ensuring robust security practices, conducting regular security audits, and
promptly addressing vulnerabilities to protect millions of production deployments. π
- [x] **Documentation:** Creating comprehensive guides, tutorials, and examples to help users of all skill levels. π
## How Sponsorship Works
We currently manage sponsorships *exclusively* through **GitHub Sponsors**. This platform integrates seamlessly with the GitHub ecosystem, making it easy for organizations to contribute.
