{"id":4059,"library":"jinja2-ansible-filters","title":"Jinja2 Ansible Filters","description":"Jinja2 Ansible Filters (current version 1.3.2) is a Python library that ports many of Ansible's Jinja2 filters, allowing them to be used independently without requiring the full Ansible core. This is particularly useful for projects needing specific Ansible-style data transformations within a standard Jinja2 templating environment. The library has a sporadic release cadence, with the last update in June 2022.","status":"active","version":"1.3.2","language":"en","source_language":"en","source_url":"https://gitlab.com/shobe/jinja2-ansible-filters","tags":["jinja2","ansible","filters","templating","utility"],"install":[{"cmd":"pip install jinja2-ansible-filters","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core templating engine this library extends.","package":"jinja2","optional":false},{"reason":"Required for filters that handle YAML data.","package":"pyyaml","optional":false}],"imports":[{"note":"This class extends Jinja2's Environment and automatically registers Ansible-compatible filters.","symbol":"AnsibleEnvironment","correct":"from jinja2_ansible_filters import AnsibleEnvironment"}],"quickstart":{"code":"from jinja2_ansible_filters import AnsibleEnvironment\n\n# Create an environment that includes Ansible's Jinja2 filters\nenv = AnsibleEnvironment()\n\n# Example 1: Use a basic filter (e.g., capitalize)\ntemplate1 = env.from_string(\"{{ 'hello world' | capitalize }}\")\nprint(f\"Capitalize: {template1.render()}\")\n\n# Example 2: Use a list filter (e.g., unique)\ndata = {'items': ['apple', 'banana', 'apple', 'orange']}\ntemplate2 = env.from_string(\"{{ items | unique | join(', ') }}\")\nprint(f\"Unique items: {template2.render(data)}\")\n\n# Example 3: Use a default filter\ndata2 = {'name': 'Alice'}\ntemplate3 = env.from_string(\"Hello {{ username | default('Guest') }}\")\nprint(f\"With defined var: {template3.render(username=data2['name'])}\")\nprint(f\"With undefined var: {template3.render()}\")","lang":"python","description":"Initialize a Jinja2 environment using `AnsibleEnvironment` to automatically load the provided filters, then render templates with various Ansible-style filters."},"warnings":[{"fix":"Upgrade to `jinja2-ansible-filters` version 1.3.2 or later. If issues persist, ensure your Jinja2 version is compatible or consider pinning Jinja2 to `<3.1` (though this might limit other library dependencies).","message":"Versions of `jinja2-ansible-filters` prior to 1.3.2 (released June 2022) were incompatible with Jinja2 versions 3.1 and later. This was due to internal Jinja2 filter decorators being renamed (`environmentfilter` to `pass_environment`), leading to import errors like 'cannot import name 'environmentfilter''.","severity":"breaking","affected_versions":"<1.3.2"},{"fix":"To make the `default` filter apply to falsy values, pass `true` as a second argument, e.g., `{{ my_var | default('fallback', true) }}`.","message":"The `default` (or `d`) filter in Jinja2, including those provided by this library, by default only applies if a variable is *truly undefined*. It will NOT apply if the variable is defined but evaluates to a 'falsy' value (e.g., empty string `''`, `False`, `0`, or `None`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use the `is` operator for Jinja tests: `when: result is failed`. Ensure you are using a filter, not a test, when applying the pipe `|` operator.","message":"Ansible has historically deprecated and removed the ability to use 'Jinja tests' (e.g., `is failed`, `is successful`) with the filter pipe (`|`) syntax (e.g., `result | failed`). While this library provides filters, users accustomed to older Ansible patterns might incorrectly attempt this, leading to `AnsibleFilterError`.","severity":"gotcha","affected_versions":"All versions (reflects upstream Ansible/Jinja2 behavior)"},{"fix":"Explicitly convert the intermediate result to a list using the `|list` filter before applying `join`, e.g., `{{ items | selectattr('active') | map(attribute='name') | list | join(', ') }}`.","message":"When chaining certain Jinja2 filters, particularly `map` or `selectattr` followed by `join`, the intermediate result might not be a list type that `join` expects directly. This can lead to unexpected output or errors.","severity":"gotcha","affected_versions":"All versions (standard Jinja2 behavior)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}