{"id":1776,"library":"uvicorn-worker","title":"Uvicorn Worker for Gunicorn","description":"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.","status":"active","version":"0.4.0","language":"en","source_language":"en","source_url":"https://github.com/Kludex/uvicorn-worker","tags":["asgi","uvicorn","gunicorn","web-server","worker","fastapi","starlette"],"install":[{"cmd":"pip install uvicorn-worker gunicorn","lang":"bash","label":"Install uvicorn-worker and Gunicorn"}],"dependencies":[{"reason":"This package enhances and replaces Uvicorn's internal Gunicorn workers, building upon Uvicorn's base.","package":"uvicorn","optional":false},{"reason":"This library provides workers specifically for use with the Gunicorn WSGI HTTP server.","package":"gunicorn","optional":false}],"imports":[{"note":"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.","wrong":"from uvicorn_worker import UvicornWorker","symbol":"UvicornWorker","correct":"gunicorn main:app -k uvicorn.workers.UvicornWorker"}],"quickstart":{"code":"import uvicorn\n\nasync def app(scope, receive, send):\n    assert scope['type'] == 'http'\n    await send({\n        'type': 'http.response.start',\n        'status': 200,\n        'headers': [\n            [b'content-type', b'text/plain'],\n        ],\n    })\n    await send({\n        'type': 'http.response.body',\n        'body': b'Hello from Uvicorn Worker!\\n',\n    })\n\n# To run this with Gunicorn and uvicorn-worker:\n# 1. Save the above code as `main.py`\n# 2. Run in your terminal:\n#    gunicorn main:app -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000\n# 3. Access at http://localhost:8000","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer.","message":"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`.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Ensure your `uvicorn` package version meets the requirements of your `uvicorn-worker` version. Check the `uvicorn-worker` changelog for specific compatibility.","message":"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.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Always use `gunicorn ... -k uvicorn.workers.UvicornWorker`. The presence of the `uvicorn-worker` package ensures the enhanced implementation is used.","message":"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`.","severity":"gotcha","affected_versions":"All"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}