https://github.com/Kludex/uvicorn
The lightning-fast ASGI server. 🦄
https://github.com/Kludex/uvicorn
Last synced: about 2 months ago
JSON representation
The lightning-fast ASGI server. 🦄
- Host: GitHub
- URL: https://github.com/Kludex/uvicorn
- Owner: Kludex
- License: bsd-3-clause
- Fork: true (encode/uvicorn)
- Created: 2021-11-18T17:51:57.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2023-07-30T20:08:40.000Z (over 2 years ago)
- Last Synced: 2024-05-01T16:32:13.057Z (over 1 year ago)
- Language: Python
- Homepage: https://www.uvicorn.org/
- Size: 3.04 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
- best-of-web-python - GitHub - 3% open · ⏱️ 01.10.2025): (Servers)
README
An ASGI web server, for Python.
---
[](https://github.com/encode/uvicorn/actions)
[](https://pypi.python.org/pypi/uvicorn)
[](https://pypi.org/project/uvicorn)
**Documentation**: [https://www.uvicorn.org](https://www.uvicorn.org)
---
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