{"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":"python","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,"search_vec":"'0.4.0':46 'allow':28 'as-need':51 'asgi':61 'bundl':21 'cadenc':55 'coincid':57 'compat':33 'continu':35 'current':43 'design':15 'develop':31 'direct':22 'enhanc':10 'fastapi':68 'follow':49 'futur':32 'gunicorn':4,14,40,63 'improv':36 'independ':30 'integr':41 'need':53 'often':56 'packag':26 'previous':20 'provid':8 'releas':54 'replac':17 'server':66 'starlett':69 'updat':60 'uvicorn':1,6,11,25,38,59,62 'uvicorn-work':5 'version':44 'web':65 'web-serv':64 'within':23 'worker':2,7,12,19,67","created_at":"2026-04-09T04:02:38.314568+00:00","updated_at":"2026-04-17T00:07:26.131889+00:00","problems":{"verify_error":"no import statement found"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.4.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/Kludex/uvicorn-worker","docs":null,"changelog":"https://github.com/Kludex/uvicorn-worker/releases","pypi":"https://pypi.org/project/uvicorn-worker/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-05","install_tag":null}}