Install & Compatibility
Where this runs
tested against v0.18.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
46MB installed
● package 46MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Config
✓ from hypercorn.config import Config
serve (asyncio)
✓ from hypercorn.asyncio import serve
serve (trio)
✓ from hypercorn.trio import serve
run
✓ from hypercorn.run import run
✗ asyncio.run(serve(app, Config())) without explicit 'run'
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.
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.
import asyncio
from hypercorn.config import Config
from hypercorn.asyncio import serve
async def app(scope, receive, send):
assert scope['type'] == 'http'
response_body = b'Hello, world!'
headers = [
(b'content-type', b'text/plain'),
(b'content-length', str(len(response_body)).encode())
]
await send({'type': 'http.response.start', 'status': 200, 'headers': headers})
await send({'type': 'http.response.body', 'body': response_body})
async def main():
config = Config()
config.bind = [f"0.0.0.0:{os.environ.get('PORT', '8000')}"]
print(f"Serving on {config.bind[0]}...")
await serve(app, config)
if __name__ == '__main__':
import os
asyncio.run(main())
hypercorn --version
Debug
Known issues
breakingHypercorn dropped support for ASGI/2 and now requires ASGI/3 applications. Applications built against older ASGI/2 specifications will need to be updated.fixEnsure your ASGI application conforms to the ASGI/3 specification. Most modern ASGI frameworks (FastAPI, Starlette, Quart) already support ASGI/3.
affects: >=0.15.0
deprecatedThe 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.fixUpdate command-line scripts to use `--access-logfile` and `--error-logfile` respectively.
affects: >=0.15.0
gotchaWhen running Hypercorn with the `--reload` option inside Docker containers, changes to files mounted via Docker volumes may not trigger a reload as expected.fixEnsure 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.
affects: All versions with `--reload`
gotchaSome 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.fixMonitor 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.
affects: All versions, especially pre-0.15.0
gotchaThere 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.fixFor 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.
affects: All versions
Errors
Common errors & fixes
ValueError: not enough values to unpack (expected 2, got 1)
This error occurs when the `--bind` argument is provided with only a port number (e.g., `--bind 8000` or `--bind $PORT`) without a host address, whereas Hypercorn expects a `host:port` pair.
fixSpecify both the host and port, such as `hypercorn --bind 0.0.0.0:8000 module:app` or `hypercorn --bind 0.0.0.0:$PORT module:app` in deployment environments.
RuntimeError: no running event loop
This error typically arises when Hypercorn's configured worker class (e.g., `trio`) does not match the event loop expected by the ASGI application (e.g., `asyncio`), or vice-versa, leading to a conflict in asynchronous execution environments.
fixEnsure the Hypercorn worker class (`-k` option) aligns with your application's asynchronous framework. For `asyncio` applications (the default for many ASGI apps), use `hypercorn -k asyncio module:app` or omit `-k` to use the default. If your application is built with `trio`, explicitly set `hypercorn -k trio module:app`.
hypercorn.utils.LifespanTimeoutError: Timeout whilst awaiting startup
This indicates that your ASGI application's startup phase, as defined by the ASGI Lifespan protocol, is taking too long to complete or is not correctly signaling its readiness to Hypercorn, causing the server to timeout.
fixEither increase the `startup_timeout` configuration option for Hypercorn (e.g., `hypercorn --startup-timeout 60 module:app`) or, more importantly, debug your ASGI application to ensure its startup logic completes promptly and correctly sends the `{"type": "lifespan.startup.complete"}` message. AttributeError: 'module' object has no attribute 'run'
This error occurs when attempting to call a non-existent `.run()` method on an application module or on Hypercorn itself, typically when developers are accustomed to frameworks (like Flask) that expose an `app.run()` function for development. Hypercorn does not provide such a method directly on the application object.
fixTo run your application with Hypercorn, use the command-line interface: `hypercorn module:app`. If you need to run it programmatically, use `asyncio.run(hypercorn.asyncio.serve(app, config))` as shown in Hypercorn's API usage documentation.
Upgrade
Version history
0.18.0latest on PyPI · released Nov 8, 2025
Audit
Dependencies
h11requiredHTTP/1.1 protocol implementation
h2requiredHTTP/2 protocol implementation
wsprotorequiredWebSockets protocol implementation
priorityrequiredHTTP/2 priority tree implementation
typing-extensionsrequiredBackported and experimental type hints
aioquicoptionalRequired for HTTP/3 support (install with 'hypercorn[h3]')
uvloopoptionalOptional faster asyncio event loop (install with 'hypercorn[uvloop]')
triooptionalOptional alternative async concurrency library (install with 'hypercorn[trio]')