Install & Compatibility
Where this runs
tested against v25.12.1 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.615s · 40.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.5s · import 0.543s · 42MB
44MB installed
● package 44MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Sanic
✓ from sanic import Sanic
Response types
✓ from sanic.response import text, json
✗ return "Hello, world!" or return {"foo": "bar"}
Sanic requires explicit response objects (e.g., `text()`, `json()`) unlike some other frameworks that implicitly convert return values.
Request
✓ async def handler(request: Request):
✗ from sanic.ctx import request
The `request` object is always passed as the first argument to route handlers, not accessed via a global context variable.
This minimal Sanic application defines a single GET route at the root path ('/') that returns 'Hello, world.' It demonstrates app initialization, route decoration, explicit asynchronous handler definition, and using a Sanic response object. Run with `python your_app.py` or `sanic your_app:app --debug`.
from sanic import Sanic
from sanic.response import text
app = Sanic("MyHelloWorldApp")
@app.get("/")
async def hello_world(request):
return text("Hello, world.")
if __name__ == "__main__":
app.run(host="0.0.0.0", port=8000, debug=True)
sanic --version
Debug
Known issues
breakingSanic requires explicit response objects (e.g., `text()`, `json()`). Unlike frameworks like Flask, returning raw strings or dictionaries from handlers is not supported and will result in errors, as Sanic aims to avoid implicit conversions for performance.fixAlways wrap your return values in a `sanic.response` object, such as `text()`, `json()`, `html()`, or `file()`.
affects: All versions
breakingThe functionality and parsing of `Request.accept` changed significantly. Relying on its equality operations may produce incorrect results. The `match()` method is now the preferred way to interact with `Request.accept`.fixTransition to using `request.accept.match()` for content type negotiation.
affects: >=23.3.0
breakingResponse cookies are no longer dict-like objects. Direct dictionary methods (e.g., `cookie['key'] = value`) for `response.cookies` were removed.fixAccess and manipulate response cookies using object-oriented methods (e.g., `response.cookies['key']`, `del response.cookies['key']`) rather than dictionary-specific methods (like `.update()` or `.items()`).
affects: >=24.3.0 (warnings started in 23.3.0)
breakingDuplicate route names are no longer allowed. Registering multiple routes with the same name will raise a `sanic.exceptions.ServerError`.fixEnsure all routes have unique names. You can explicitly set a name using the `name` parameter in the `@app.route()` decorator or by ensuring function/class names are unique.
affects: >=23.3.0 (warnings started in 22.9.0)
deprecatedThe `sanic.worker.GunicornWorker` class has been removed. Running Sanic with Gunicorn should now be done via `uvicorn` as an ASGI application.fixMigrate Gunicorn deployments to use Uvicorn for serving Sanic applications. Refer to Uvicorn's documentation for integration with Gunicorn.
affects: >=22.12.0 (removed in 23.3.0)
gotcha`uvloop` is Unix-specific. If `uvloop` is enabled (which is the default on supported platforms), Sanic applications may not run or perform optimally on Windows. You can explicitly disable `uvloop` via an environment variable.fixOn Windows, either set `SANIC_NO_UVLOOP=true` before installing/running, or use a Linux-based environment (e.g., WSL, Docker) for development and deployment.
affects: All versions
Errors
Common errors & fixes
AttributeError: 'Request' object has no attribute 'json'
The request body's content type is not `application/json`, so Sanic does not parse the data into the `request.json` attribute.
fix@app.post("/submit")
async def handler(request):
# Access based on Content-Type:
# For 'application/json':
data = request.json
# For 'application/x-www-form-urlencoded' or 'multipart/form-data':
# data = request.form
# For URL query parameters:
# data = request.args
return response.json({"status": "success"}) TypeError: 'coroutine' object is not awaitable
An asynchronous (async) function was called without the `await` keyword, meaning its return value is a coroutine object itself, not its resolved result.
fixasync def my_async_task():
await asyncio.sleep(0.1)
return "task completed"
@app.get("/")
async def handler(request):
result = await my_async_task() # Correct: use 'await'
return response.text(result) Sanic.app is no longer supported, use the application context from sanic.app.current_app
The global `Sanic.app` object was deprecated and removed in Sanic versions 21.12+, requiring the application instance to be accessed via `sanic.app.current_app` or `request.app`.
fixfrom sanic.app import current_app
# To access the app instance globally or outside a handler:
app_instance = current_app
print(app_instance.name)
# To access the app instance within a request handler:
@app.get("/")
async def handler(request):
return response.text(f"App name: {request.app.name}") ModuleNotFoundError: No module named 'uvloop'
The optional `uvloop` package, which Sanic can use for improved performance, is being referenced or configured without being installed in the Python environment.
AttributeError: 'Sanic' object has no attribute 'run'
The `app.run()` method was deprecated in Sanic v21.12.0 and completely removed in v22.3.
fixUse `sanic.run(app)` to start your application or execute it via the command line: `python -m sanic server.app`.
Upgrade
Version history
25.12.1latest on PyPI · released May 31, 2026
Audit
Dependencies
uvloopoptionalUsed by default on Unix-like systems for increased performance; can be disabled with SANIC_NO_UVLOOP=true.
ujsonoptionalUsed by default for faster JSON processing; can be disabled with SANIC_NO_UJSON=true.
httptoolsrequiredCore dependency for HTTP protocol parsing.
aiofilesrequiredCore dependency for asynchronous file operations.
websocketsrequiredCore dependency for WebSocket functionality.