Registry / web-framework / uvicorn-worker

uvicorn-worker

library0.4.0pypypi✓ verified 27d ago

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.

web-framework

pip install uvicorn-worker gunicorn

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · UVICORN-WORKER

uvicorn-worker

web-frameworkpythonv0.4.0

Install

2.0s avg

Import

—

Disk

20MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 21.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.0s · import 0.000s · 22MB

20MB installed

● package 20MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UvicornWorker

✓ gunicorn main:app -k uvicorn.workers.UvicornWorker

✗ from uvicorn_worker import 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.

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

Debug

Known issues

breakingPython 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.

affects: >=0.3.0

breakingCompatibility 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.

affects: >=0.3.0

gotchaDespite 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.

affects: All

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.

affects: All

Upgrade

Version history

0.4.0latest on PyPI · released Sep 20, 2025

Audit

Dependencies

uvicornrequiredThis package enhances and replaces Uvicorn's internal Gunicorn workers, building upon Uvicorn's base.

gunicornrequiredThis library provides workers specifically for use with the Gunicorn WSGI HTTP server.

Agent activity

6 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Kludex/uvicorn-worker ↗

packagehttps://pypi.org/project/uvicorn-worker/ ↗

changeloghttps://github.com/Kludex/uvicorn-worker/releases ↗