You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

Filter plugins

Filter plugins manipulate data. With the right filter you can extract a particular value, transform data types and formats, perform mathematical calculations, split and concatenate strings, insert dates and times, and do much more. Ansible uses the standard filters shipped with Jinja2 and adds some specialized filter plugins. You can create custom Ansible filters as plugins.

Enabling filter plugins 

You can add a custom filter plugin by dropping it into a filter_plugins directory adjacent to your play, inside a role, or by putting it in one of the filter plugin directory sources configured in ansible.cfg.

Using filter plugins 

You can use filters anywhere you can use templating in Ansible: in a play, in variables file, or in a Jinja2 template for the template module. For more information on using filter plugins, see Using filters to manipulate data. Filters can return any type of data, but if you want to always return a boolean (True or False) you should be looking at a test instead.

vars:
   yaml_string: "{{ some_variable|to_yaml }}"

Filters are the preferred way to manipulate data in Ansible, you can identify a filter because it is normally preceded by a |, with the expression on the left of it being the first input of the filter. Additional parameters may be passed into the filter itself as you would to most programming functions. These parameters can be either positional (passed in order) or named (passed as key=value pairs). When passing both types, positional arguments should go first.

passing_positional: {{ (x == 32) | ternary('x is 32', 'x is not 32') }}
passing_extra_named_parameters: {{ some_variable | to_yaml(indent=8, width=1337) }}
passing_both: {{ some_variable| ternary('true value', 'false value', none_val='NULL') }}

In the documentation, filters will always have a C(_input) option that corresponds to the expression to the left of c(|). A C(positional:) field in the documentation will show which options are positional and in which order they are required.

Plugin list 

You can use ansible-doc -t filter -l to see the list of available plugins. Use ansible-doc -t filter <plugin name> to see plugin-specific documentation and examples.

Filter plugins

Enabling filter plugins

Using filter plugins

Plugin list

Enabling filter plugins 

Using filter plugins 

Plugin list 