README.md
1<p align="center">
2 <img width="320" height="320" src="https://raw.githubusercontent.com/tomchristie/uvicorn/master/docs/uvicorn.png" alt='uvicorn'>
3</p>
4
5<p align="center">
6<em>The lightning-fast ASGI server.</em>
7</p>
8
9---
10
11[](https://github.com/encode/uvicorn/actions)
12[](https://pypi.python.org/pypi/uvicorn)
13
14**Documentation**: [https://www.uvicorn.org](https://www.uvicorn.org)
15
16**Requirements**: Python 3.6+ (For Python 3.5 support, install version 0.8.6.)
17
18Uvicorn is a lightning-fast ASGI server implementation, using [uvloop][uvloop] and [httptools][httptools].
19
20Until recently Python has lacked a minimal low-level server/application interface for
21asyncio frameworks. The [ASGI specification][asgi] fills this gap, and means we're now able to
22start building a common set of tooling usable across all asyncio frameworks.
23
24Uvicorn currently supports HTTP/1.1 and WebSockets. Support for HTTP/2 is planned.
25
26## Quickstart
27
28Install using `pip`:
29
30```shell
31$ pip install uvicorn
32```
33
34This will install uvicorn with minimal (pure Python) dependencies.
35
36```shell
37$ pip install uvicorn[standard]
38```
39
40This will install uvicorn with "Cython-based" dependencies (where possible) and other "optional extras".
41
42In this context, "Cython-based" means the following:
43
44- the event loop `uvloop` will be installed and used if possible.
45- the http protocol will be handled by `httptools` if possible.
46
47Moreover, "optional extras" means that:
48
49- the websocket protocol will be handled by `websockets` (should you want to use `wsproto` you'd need to install it manually) if possible.
50- the `--reloader` flag in development mode will use `watchgod`.
51- windows users will have `colorama` installed for the colored logs.
52- `python-dotenv` will be installed should you want to use the `--env-file` option.
53- `PyYAML` will be installed to allow you to provide a `.yaml` file to `--log-config`, if desired.
54
55Create an application, in `example.py`:
56
57```python
58async def app(scope, receive, send):
59 assert scope['type'] == 'http'
60
61 await send({
62 'type': 'http.response.start',
63 'status': 200,
64 'headers': [
65 [b'content-type', b'text/plain'],
66 ],
67 })
68 await send({
69 'type': 'http.response.body',
70 'body': b'Hello, world!',
71 })
72```
73
74Run the server:
75
76```shell
77$ uvicorn example:app
78```
79
80---
81
82<p align="center"><i>Uvicorn is <a href="https://github.com/encode/uvicorn/blob/master/LICENSE.md">BSD licensed</a> code.<br/>Designed & built in Brighton, England.</i><br/>— �� —</p>
83
84[uvloop]: https://github.com/MagicStack/uvloop
85[httptools]: https://github.com/MagicStack/httptools
86[asgi]: https://asgi.readthedocs.io/en/latest/
87
){kind=link}
){kind=link}