aiohttp-jinja2 is a Jinja2 template renderer designed for integration with aiohttp.web, the HTTP server component of the asyncio-based aiohttp library. Currently at version 1.6, it provides a stable and mature solution for serving dynamic HTML content within aiohttp applications, with releases occurring a few times a year to maintain compatibility and introduce new features.
Install & Compatibility
Where this runs
tested against v1.6 · 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.925 runs
installs and imports cleanly · install 0.0s · import 0.762s · 28.6MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 4.1s · import 0.696s · 31MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
setup
✓ import aiohttp_jinja2
from aiohttp import web
import jinja2
app = web.Application()
aiohttp_jinja2.setup(app, loader=jinja2.FileSystemLoader('templates'))
Initializes the Jinja2 environment for the aiohttp application.
template
✓ from aiohttp import web
import aiohttp_jinja2
@routes.get('/hello')
@aiohttp_jinja2.template('index.html')
async def handler(request: web.Request):
return {'name': 'World'}
✗ @aiohttp_jinja2.template('index.html')
@routes.get('/hello')
async def handler(request: web.Request): ...
The `@template` decorator must be applied *before* route decorators like `@routes.get()` to ensure proper functionality.
render_template
✓ from aiohttp import web
import aiohttp_jinja2
async def handler(request: web.Request):
context = {'data': 'Some info'}
response = aiohttp_jinja2.render_template('page.html', request, context)
response.headers['Content-Language'] = 'en'
return response
For handlers requiring more control over the response (e.g., setting headers) or explicit rendering.
This quickstart demonstrates how to set up `aiohttp-jinja2` with an `aiohttp.web` application. It initializes the Jinja2 environment, defines a template directory, and uses the `@aiohttp_jinja2.template` decorator to render HTML responses for different routes. Create a 'templates' directory with `index.html` and `hello.html` files (e.g., `index.html`: `<h1>{{ title }}</h1>`, `hello.html`: `<h1>Hello, {{ name }}!</h1>`).
import os
from aiohttp import web
import aiohttp_jinja2
import jinja2
async def hello_page(request):
name = request.match_info.get('name', 'Anonymous')
return {'name': name, 'title': 'Hello Page'}
async def welcome_page(request):
return {'title': 'Welcome'}
def setup_routes(app):
aiohttp_jinja2.setup(
app,
loader=jinja2.FileSystemLoader(
os.path.join(os.path.dirname(__file__), 'templates')
)
)
routes = web.RouteTableDef()
@routes.get('/')
@aiohttp_jinja2.template('index.html')
async def index(request: web.Request):
return await welcome_page(request)
@routes.get('/hello/{name}')
@aiohttp_jinja2.template('hello.html')
async def hello(request: web.Request):
return await hello_page(request)
app.add_routes(routes)
if __name__ == '__main__':
app = web.Application()
setup_routes(app)
web.run_app(app, port=8080)
Debug
Known issues
breakingThe `static_root_url` key for accessing static file configuration has been deprecated in favor of `aiohttp.web.AppKey`. Update application configuration to use `AppKey` instances.fixReplace direct string key access (e.g., `app['static_root_url']`) with `aiohttp.web.AppKey` instances for configuration.
affects: >=1.6
breakingPython 3.7 is no longer supported. The library now requires Python 3.8 or newer.fixUpgrade your Python environment to 3.8, 3.9, 3.10, 3.11, or 3.12.
affects: >=1.6
breakingJinja2 versions older than 3.0 are no longer supported. This can lead to package conflicts if other dependencies require older Jinja2 versions.fixEnsure `jinja2` is installed at version `3.0.0` or higher.
affects: >=1.5
deprecatedDecorating non-async functions with `@aiohttp_jinja2.template` is no longer supported. All web handlers using this decorator must be `async` functions.fixRefactor web handlers decorated with `@aiohttp_jinja2.template` to be `async def` functions.
affects: >=1.5.1 (deprecated since 0.16)
gotchaAsynchronous functions (coroutines) cannot be directly called from within Jinja2 templates. They must be awaited in the handler before passing their results to the template context.fixEnsure any data requiring an `await` call is resolved in your `aiohttp` handler before constructing the context dictionary passed to the template.
affects: All versions
gotchaWhen using `aiohttp.web.RouteTableDef` with `@aiohttp_jinja2.template`, the `@template` decorator must be applied *before* the `@routes.get()` (or other HTTP method) decorator.fixCorrect the decorator order: `
@routes.get('/path')
@aiohttp_jinja2.template('template.html')
async def handler(...): ...
` affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'aiohttp_jinja2'
The `aiohttp-jinja2` library has not been installed in the Python environment where the application is being run.
fixInstall the library using pip: `pip install aiohttp-jinja2`
jinja2.exceptions.TemplateNotFound: 'your_template_name.jinja2'
The Jinja2 environment was not configured with a loader that can find the specified template file, or the template file does not exist at the path the loader is configured to search.
fixEnsure `aiohttp_jinja2.setup()` is called with a correct `jinja2.FileSystemLoader` (or other appropriate loader) pointing to your template directory, and verify that 'your_template_name.jinja2' exists within that path.
TypeError: 'Response' object is not iterable
When a handler is decorated with `@aiohttp_jinja2.template`, it is expected to return a dictionary that serves as the context for the template. Returning an `aiohttp.web.Response` object directly will cause this error, as the decorator handles response creation.
fixModify the decorated handler function to return only a dictionary of context variables, letting the `@template` decorator construct the `aiohttp.web.Response` object.
Audit
Dependencies
aiohttprequiredCore web framework for asyncio. Requires aiohttp >= 3.6.3.
jinja2requiredThe template engine rendered by this library. Requires jinja2 >= 3.0.0.