Install & Compatibility
Where this runs
tested against v1.3.2 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.300s · 21.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.286s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AnsibleCoreFiltersExtension
✓ from jinja2_ansible_filters import AnsibleCoreFiltersExtension
✗ from jinja2_ansible_filters import AnsibleEnvironment
Extension
✓ from jinja2_ansible_filters import Extension
FilterModule
✓ from jinja2_ansible_filters import FilterModule
Initialize a Jinja2 environment using `AnsibleEnvironment` to automatically load the provided filters, then render templates with various Ansible-style filters.
from jinja2_ansible_filters import AnsibleEnvironment
# Create an environment that includes Ansible's Jinja2 filters
env = AnsibleEnvironment()
# Example 1: Use a basic filter (e.g., capitalize)
template1 = env.from_string("{{ 'hello world' | capitalize }}")
print(f"Capitalize: {template1.render()}")
# Example 2: Use a list filter (e.g., unique)
data = {'items': ['apple', 'banana', 'apple', 'orange']}
template2 = env.from_string("{{ items | unique | join(', ') }}")
print(f"Unique items: {template2.render(data)}")
# Example 3: Use a default filter
data2 = {'name': 'Alice'}
template3 = env.from_string("Hello {{ username | default('Guest') }}")
print(f"With defined var: {template3.render(username=data2['name'])}")
print(f"With undefined var: {template3.render()}")
Debug
Known issues
breakingVersions 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''.fixUpgrade 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).
affects: <1.3.2
gotchaThe `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`).fixTo make the `default` filter apply to falsy values, pass `true` as a second argument, e.g., `{{ my_var | default('fallback', true) }}`. affects: All versions
gotchaAnsible 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`.fixUse the `is` operator for Jinja tests: `when: result is failed`. Ensure you are using a filter, not a test, when applying the pipe `|` operator.
affects: All versions (reflects upstream Ansible/Jinja2 behavior)
gotchaWhen 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.fixExplicitly convert the intermediate result to a list using the `|list` filter before applying `join`, e.g., `{{ items | selectattr('active') | map(attribute='name') | list | join(', ') }}`. affects: All versions (standard Jinja2 behavior)
Upgrade
Version history
1.3.2latest on PyPI · released Jun 30, 2022
Audit
Dependencies
jinja2requiredCore templating engine this library extends.
pyyamlrequiredRequired for filters that handle YAML data.