Install & Compatibility
Where this runs
tested against v25.12.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
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.000s · 40.9MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 3.2s · import 0.000s · 42MB
40MB installed
● package 40MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Extend
✓ from sanic_ext import Extend
✗ from sanic_ext import Extend
This quickstart demonstrates how to initialize Sanic-Ext with a Sanic application and use its dependency injection feature for route handlers. By type-hinting parameters in a route function, Sanic-Ext automatically extracts them from the request (e.g., query parameters, path parameters, or request body) and performs basic validation. After running, you can typically access OpenAPI documentation at `/docs` or `/swagger` in your browser.
from sanic import Sanic
from sanic_ext import Extend
from typing import Optional
app = Sanic("My App with Sanic-Ext")
Extend(app)
@app.get("/")
async def hello_world(name: str = "World"):
# Sanic-Ext automatically injects query parameters based on type hints
return {"hello": name}
@app.post("/items")
async def create_item(item_id: int, description: Optional[str] = None):
# This demonstrates basic type-hinted injection for path/query parameters
return {"item_id": item_id, "description": description, "status": "created"}
if __name__ == "__main__":
# Run the Sanic application
# Sanic-Ext provides features like OpenAPI docs at /docs or /swagger
app.run(host="0.0.0.0", port=8000, debug=True)
Debug
Known issues
breakingSanic-Ext versions are tightly coupled with Sanic framework versions. For example, `sanic-ext==25.12.0` is intended for use with `sanic>=23.12,<26.0`. Using a significantly older or newer Sanic version with an incompatible `sanic-ext` version can lead to runtime errors or unexpected behavior.fixAlways install `sanic-ext` with a major version that matches or is compatible with your `sanic` installation. Refer to Sanic-Ext's documentation for specific version compatibility matrices.
affects: <25.12.0 (and future versions if mismatch occurs)
gotchaThe behavior and capabilities of request data validation and OpenAPI schema generation have evolved across versions, especially with the introduction of `msgspec` support in `v23.12.0` and refinements to `pydantic`/`attrs` integration. Default type coercions or schema representations might differ slightly.fixIf migrating from older versions, thoroughly test your API endpoints and review generated OpenAPI documentation. Consider explicitly installing `sanic-ext[msgspec]` or `sanic-ext[pydantic]` to leverage specific validation libraries.
affects: <23.12.0
gotchaPrior to `v25.12.0`, Sanic-Ext could experience `KeyErrors` in query parameter validation under certain conditions. Additionally, issues related to handler list mutation (when dynamically adding/removing handlers) were present.fixUpgrade to `sanic-ext==25.12.0` or newer to benefit from fixes addressing `KeyErrors` in query param validation and handler list mutation stability. If upgrading is not immediately possible, avoid dynamic modification of handler lists after `Extend(app)` is called.
affects: <25.12.0
gotchaIn versions prior to `v25.12.0`, the background logger might fail to remove unpickleable items, potentially leading to resource leaks or unexpected behavior in long-running applications that utilize background logging.fixUpgrade to `sanic-ext==25.12.0` or newer to resolve issues with the background logger failing to remove unpickleable items. Ensure that objects passed to background tasks are pickleable where necessary.
affects: <25.12.0
Upgrade
Version history
25.12.0latest on PyPI · released Jan 20, 2026
Audit
Dependencies
sanicrequiredCore web framework Sanic-Ext extends. Compatibility is tied to Sanic's major version.
msgspecoptionalOptional dependency for high-performance data validation and serialization/deserialization. Enabled via sanic-ext[msgspec].
pydanticoptionalOptional dependency for data validation, enabled via sanic-ext[pydantic].