Uvicorn Worker for Gunicorn

0.4.0 · active · verified Thu Apr 09

uvicorn-worker provides an enhanced Uvicorn worker for Gunicorn, designed to replace the workers previously bundled directly within the `uvicorn` package. This allows for independent development, future compatibility, and continued improvements of Uvicorn's Gunicorn integration. The current version is 0.4.0, and it follows an as-needed release cadence, often coinciding with `uvicorn` updates.

Warnings

breaking Python 3.8 support was dropped in version 0.3.0. Users on Python 3.8 or older must either upgrade Python or use an older version of `uvicorn-worker`.
Fix: Upgrade your Python environment to 3.9 or newer.
breaking Compatibility with `uvicorn` versions changes. `uvicorn-worker` 0.3.0 required `uvicorn >= 0.15.0`, while 0.4.0 requires `uvicorn >= 0.36.0`. Using an incompatible `uvicorn` version can lead to runtime errors.
Fix: Ensure your `uvicorn` package version meets the requirements of your `uvicorn-worker` version. Check the `uvicorn-worker` changelog for specific compatibility.
gotcha Despite being provided by the `uvicorn-worker` package, the Gunicorn worker class is specified as `uvicorn.workers.UvicornWorker`. This is a deliberate design choice for backward compatibility with older `uvicorn` installations, where the worker was internal. Do not attempt to use `-k uvicorn_worker.UvicornWorker`.
Fix: Always use `gunicorn ... -k uvicorn.workers.UvicornWorker`. The presence of the `uvicorn-worker` package ensures the enhanced implementation is used.
gotcha `uvicorn-worker` is a distinct package designed to replace and improve the Gunicorn workers that were historically part of `uvicorn`. While `uvicorn` might still provide a stub or basic worker, installing `uvicorn-worker` ensures you are using the actively maintained and recommended version.
Fix: For Gunicorn deployments with Uvicorn, always `pip install uvicorn-worker` in addition to `uvicorn` and `gunicorn` to ensure you benefit from the latest features and fixes.

Install

pip install uvicorn-worker gunicorn Install uvicorn-worker and Gunicorn

Imports

UvicornWorker
```
gunicorn main:app -k uvicorn.workers.UvicornWorker
```
The `uvicorn-worker` package is designed to provide the implementation for the worker class `uvicorn.workers.UvicornWorker` that Gunicorn expects. You do not typically import `UvicornWorker` directly into your application code. Instead, you specify the Gunicorn-expected path with the `-k` flag.

Quickstart

To use `uvicorn-worker`, you need an ASGI application and Gunicorn. Create an ASGI app (e.g., `main.py`), then run Gunicorn specifying `uvicorn.workers.UvicornWorker` as the worker class. The `uvicorn-worker` package, when installed, provides the implementation for this worker path.

import uvicorn

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 from Uvicorn Worker!\n',
    })

# To run this with Gunicorn and uvicorn-worker:
# 1. Save the above code as `main.py`
# 2. Run in your terminal:
#    gunicorn main:app -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000
# 3. Access at http://localhost:8000

view raw JSON →