{"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":"python","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`: `

{{ title }}

`, `hello.html`: `

Hello, {{ name }}!

`)."},"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,"search_vec":"'1.6':31 'aiohttp':2,5,26,45,66 'aiohttp-jinja2':1,4 'aiohttp.web':16 'applic':46 'async':62 'asyncio':24 'asyncio-bas':23 'base':25 'compat':57 'compon':20 'content':43 'current':28 'design':12 'dynam':41 'featur':61 'html':42 'http':18 'integr':14 'introduc':59 'jinja2':3,6,9,65 'librari':27 'maintain':56 'matur':37 'new':60 'occur':49 'provid':33 'releas':48 'render':11,67 'serv':40 'server':19 'solut':38 'stabl':35 'templat':10,64 'time':52 'version':30 'web':63 'within':44 'year':54","created_at":"2026-04-11T09:10:31.145332+00:00","updated_at":"2026-04-15T19:31:52.865851+00:00","problems":[{"fix":"Install the library using pip: `pip install aiohttp-jinja2`","cause":"The `aiohttp-jinja2` library has not been installed in the Python environment where the application is being run.","error":"ModuleNotFoundError: No module named 'aiohttp_jinja2'"},{"fix":"Ensure `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.","cause":"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.","error":"jinja2.exceptions.TemplateNotFound: 'your_template_name.jinja2'"},{"fix":"Modify the decorated handler function to return only a dictionary of context variables, letting the `@template` decorator construct the `aiohttp.web.Response` object.","cause":"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.","error":"TypeError: 'Response' object is not iterable"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.6","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/aio-libs/aiohttp_jinja2","docs":null,"changelog":null,"pypi":"https://pypi.org/project/aiohttp-jinja2/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["web-framework","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}