{"id":2063,"library":"hypercorn","title":"Hypercorn","description":"Hypercorn is an ASGI and WSGI web server based on Hyper libraries and inspired by Gunicorn. It supports HTTP/1, HTTP/2, WebSockets (over HTTP/1 and HTTP/2), ASGI/2, and ASGI/3 specifications, and can utilize asyncio, uvloop, or trio worker types. Currently at version 0.18.0, Hypercorn is actively maintained with regular updates and focuses on robust protocol support.","status":"active","version":"0.18.0","language":"en","source_language":"en","source_url":"https://github.com/pgjones/hypercorn","tags":["asgi","wsgi","web server","http","http1","http2","http3","websockets","asyncio","trio","uvloop"],"install":[{"cmd":"pip install hypercorn","lang":"bash","label":"Standard Installation"},{"cmd":"pip install 'hypercorn[h3]'","lang":"bash","label":"With HTTP/3 Support"},{"cmd":"pip install 'hypercorn[uvloop]'","lang":"bash","label":"With uvloop for faster asyncio"}],"dependencies":[{"reason":"HTTP/1.1 protocol implementation","package":"h11","optional":false},{"reason":"HTTP/2 protocol implementation","package":"h2","optional":false},{"reason":"WebSockets protocol implementation","package":"wsproto","optional":false},{"reason":"HTTP/2 priority tree implementation","package":"priority","optional":false},{"reason":"Backported and experimental type hints","package":"typing-extensions","optional":false},{"reason":"Required for HTTP/3 support (install with 'hypercorn[h3]')","package":"aioquic","optional":true},{"reason":"Optional faster asyncio event loop (install with 'hypercorn[uvloop]')","package":"uvloop","optional":true},{"reason":"Optional alternative async concurrency library (install with 'hypercorn[trio]')","package":"trio","optional":true}],"imports":[{"symbol":"Config","correct":"from hypercorn.config import Config"},{"symbol":"serve (asyncio)","correct":"from hypercorn.asyncio import serve"},{"symbol":"serve (trio)","correct":"from hypercorn.trio import serve"},{"note":"While `asyncio.run(serve(app, Config()))` is common, `hypercorn.run.run` provides a higher-level entry point with signal handling and worker management, similar to the CLI. For basic programmatic use with full control over the event loop, `serve` is typically used.","wrong":"asyncio.run(serve(app, Config())) without explicit 'run'","symbol":"run","correct":"from hypercorn.run import run"}],"quickstart":{"code":"import asyncio\nfrom hypercorn.config import Config\nfrom hypercorn.asyncio import serve\n\nasync def app(scope, receive, send):\n    assert scope['type'] == 'http'\n    response_body = b'Hello, world!'\n    headers = [\n        (b'content-type', b'text/plain'),\n        (b'content-length', str(len(response_body)).encode())\n    ]\n    await send({'type': 'http.response.start', 'status': 200, 'headers': headers})\n    await send({'type': 'http.response.body', 'body': response_body})\n\nasync def main():\n    config = Config()\n    config.bind = [f\"0.0.0.0:{os.environ.get('PORT', '8000')}\"]\n    print(f\"Serving on {config.bind[0]}...\")\n    await serve(app, config)\n\nif __name__ == '__main__':\n    import os\n    asyncio.run(main())","lang":"python","description":"This quickstart demonstrates how to programmatically run a simple ASGI 'Hello, world!' application using Hypercorn's asyncio backend. It configures Hypercorn to bind to an address and port, defaulting to 0.0.0.0:8000, and uses `asyncio.run` to start the server. Alternatively, you can run from the command line: `hypercorn my_module:app` after installing."},"warnings":[{"fix":"Ensure your ASGI application conforms to the ASGI/3 specification. Most modern ASGI frameworks (FastAPI, Starlette, Quart) already support ASGI/3.","message":"Hypercorn dropped support for ASGI/2 and now requires ASGI/3 applications. Applications built against older ASGI/2 specifications will need to be updated.","severity":"breaking","affected_versions":">=0.15.0"},{"fix":"Update command-line scripts to use `--access-logfile` and `--error-logfile` respectively.","message":"The command-line arguments `--access-log` and `--error-log` have been deprecated in favor of `--access-logfile` and `--error-logfile` for consistency with Gunicorn's logging settings.","severity":"deprecated","affected_versions":">=0.15.0"},{"fix":"Ensure Docker volume mounts are correctly configured for file watching, or consider alternative reloading strategies for development within Docker. Verify that the file changes are indeed reflected inside the container's filesystem.","message":"When running Hypercorn with the `--reload` option inside Docker containers, changes to files mounted via Docker volumes may not trigger a reload as expected.","severity":"gotcha","affected_versions":"All versions with `--reload`"},{"fix":"Monitor memory usage closely. Consider using `uvloop` or `trio` if applicable, as they might have different memory characteristics. Review application code for potential unclosed resources or large synchronous operations blocking the event loop. The 0.15.0 release included updates to use 'more modern asyncio apis' to help address reported memory leaks.","message":"Some users have reported higher-than-expected memory usage or potential memory leaks, particularly in resource-constrained environments like serverless platforms. While improvements have been made, monitoring memory is recommended.","severity":"gotcha","affected_versions":"All versions, especially pre-0.15.0"},{"fix":"For production deployments, utilize a proper process manager (like Gunicorn acting as a supervisor) to manage Hypercorn workers. Ensure the application handles graceful shutdown signals to allow active requests to complete.","message":"There have been reports of Hypercorn not gracefully closing pending connections on `CTRL+C` or when shutting down without explicit worker management (e.g., `--workers 0`), potentially leading to HTTP 503 errors on clients.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}