{"id":2855,"library":"aiohttp-jinja2","title":"aiohttp-jinja2","description":"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.","status":"active","version":"1.6","language":"en","source_language":"en","source_url":"https://github.com/aio-libs/aiohttp_jinja2/","tags":["async","web","template","jinja2","aiohttp","renderer"],"install":[{"cmd":"pip install aiohttp-jinja2","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core web framework for asyncio. Requires aiohttp >= 3.6.3.","package":"aiohttp","optional":false},{"reason":"The template engine rendered by this library. Requires jinja2 >= 3.0.0.","package":"jinja2","optional":false}],"imports":[{"note":"Initializes the Jinja2 environment for the aiohttp application.","symbol":"setup","correct":"import aiohttp_jinja2\nfrom aiohttp import web\nimport jinja2\n\napp = web.Application()\naiohttp_jinja2.setup(app, loader=jinja2.FileSystemLoader('templates'))"},{"note":"The `@template` decorator must be applied *before* route decorators like `@routes.get()` to ensure proper functionality.","wrong":"@aiohttp_jinja2.template('index.html')\n@routes.get('/hello')\nasync def handler(request: web.Request): ...","symbol":"template","correct":"from aiohttp import web\nimport aiohttp_jinja2\n\n@routes.get('/hello')\n@aiohttp_jinja2.template('index.html')\nasync def handler(request: web.Request):\n    return {'name': 'World'}"},{"note":"For handlers requiring more control over the response (e.g., setting headers) or explicit rendering.","symbol":"render_template","correct":"from aiohttp import web\nimport aiohttp_jinja2\n\nasync def handler(request: web.Request):\n    context = {'data': 'Some info'}\n    response = aiohttp_jinja2.render_template('page.html', request, context)\n    response.headers['Content-Language'] = 'en'\n    return response"}],"quickstart":{"code":"import os\nfrom aiohttp import web\nimport aiohttp_jinja2\nimport jinja2\n\nasync def hello_page(request):\n    name = request.match_info.get('name', 'Anonymous')\n    return {'name': name, 'title': 'Hello Page'}\n\nasync def welcome_page(request):\n    return {'title': 'Welcome'}\n\ndef setup_routes(app):\n    aiohttp_jinja2.setup(\n        app, \n        loader=jinja2.FileSystemLoader(\n            os.path.join(os.path.dirname(__file__), 'templates')\n        )\n    )\n\n    routes = web.RouteTableDef()\n\n    @routes.get('/')\n    @aiohttp_jinja2.template('index.html')\n    async def index(request: web.Request):\n        return await welcome_page(request)\n\n    @routes.get('/hello/{name}')\n    @aiohttp_jinja2.template('hello.html')\n    async def hello(request: web.Request):\n        return await hello_page(request)\n\n    app.add_routes(routes)\n\n\nif __name__ == '__main__':\n    app = web.Application()\n    setup_routes(app)\n    web.run_app(app, port=8080)","lang":"python","description":"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>`)."},"warnings":[{"fix":"Replace direct string key access (e.g., `app['static_root_url']`) with `aiohttp.web.AppKey` instances for configuration.","message":"The `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.","severity":"breaking","affected_versions":">=1.6"},{"fix":"Upgrade your Python environment to 3.8, 3.9, 3.10, 3.11, or 3.12.","message":"Python 3.7 is no longer supported. The library now requires Python 3.8 or newer.","severity":"breaking","affected_versions":">=1.6"},{"fix":"Ensure `jinja2` is installed at version `3.0.0` or higher.","message":"Jinja2 versions older than 3.0 are no longer supported. This can lead to package conflicts if other dependencies require older Jinja2 versions.","severity":"breaking","affected_versions":">=1.5"},{"fix":"Refactor web handlers decorated with `@aiohttp_jinja2.template` to be `async def` functions.","message":"Decorating non-async functions with `@aiohttp_jinja2.template` is no longer supported. All web handlers using this decorator must be `async` functions.","severity":"deprecated","affected_versions":">=1.5.1 (deprecated since 0.16)"},{"fix":"Ensure any data requiring an `await` call is resolved in your `aiohttp` handler before constructing the context dictionary passed to the template.","message":"Asynchronous 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Correct the decorator order: `\n@routes.get('/path')\n@aiohttp_jinja2.template('template.html')\nasync def handler(...): ...\n`","message":"When using `aiohttp.web.RouteTableDef` with `@aiohttp_jinja2.template`, the `@template` decorator must be applied *before* the `@routes.get()` (or other HTTP method) decorator.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}