W3cubDocs

/Ansible

ansible.builtin.ini lookup – read data from an ini file

Note

This lookup plugin is part of ansible-core and included in all Ansible installations. In most cases, you can use the short plugin name ini. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.ini for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same lookup plugin name.

Synopsis

  • The ini lookup reads the contents of a file in INI format key1=value1. This plugin retrieves the value on the right side after the equal sign '=' of a given section [section].
  • You can also read a property file which - in this case - does not contain section.

Terms

Parameter

Comments

Terms

string / required

The key(s) to look up.

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('ansible.builtin.ini', key1=value1, key2=value2, ...) and query('ansible.builtin.ini', key1=value1, key2=value2, ...)

Parameter

Comments

allow_no_value

aliases: allow_none

boolean

added in ansible-core 2.12

Read an ini file which contains key without value and without ‘=’ symbol.

Choices:

  • false ← (default)
  • true

case_sensitive

string

added in ansible-core 2.12

Whether key names read from file should be case sensitive. This prevents duplicate key errors if keys only differ in case.

Default: false

default

string

Return value if the key is not in the ini file.

Default: ""

encoding

string

Text encoding to use.

Default: "utf-8"

file

string

Name of the file to load.

Default: "ansible.ini"

interpolation

boolean

added in ansible-core 2.18

Allows for interpolation of values, see https://docs.python.org/3/library/configparser.html#configparser.BasicInterpolation

Choices:

  • false
  • true ← (default)

re

boolean

Flag to indicate if the key supplied is a regexp.

Choices:

  • false ← (default)
  • true

section

string

Section where to lookup the key.

Default: "global"

type

string

Type of the file. ‘properties’ refers to the Java properties files.

Choices:

  • "ini" ← (default)
  • "properties"

Notes

Note

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('ansible.builtin.ini', term1, term2, key1=value1, key2=value2) and query('ansible.builtin.ini', term1, term2, key1=value1, key2=value2)

See Also

See also

Task paths

Search paths used for relative files.

Examples

- ansible.builtin.debug: msg="User in integration is {{ lookup('ansible.builtin.ini', 'user', section='integration', file='users.ini') }}"

- ansible.builtin.debug: msg="User in production  is {{ lookup('ansible.builtin.ini', 'user', section='production',  file='users.ini') }}"

- ansible.builtin.debug: msg="user.name is {{ lookup('ansible.builtin.ini', 'user.name', type='properties', file='user.properties') }}"

- ansible.builtin.debug:
    msg: "{{ item }}"
  loop: "{{ q('ansible.builtin.ini', '.*', section='section1', file='test.ini', re=True) }}"

- name: Read an ini file with allow_no_value
  ansible.builtin.debug:
    msg: "{{ lookup('ansible.builtin.ini', 'user', file='mysql.ini', section='mysqld', allow_no_value=True) }}"

Return Value

Key

Description

Return value

list / elements=string

value(s) of the key(s) in the ini file

Returned: success

Authors

  • Yannig Perre <yannig.perre(at)gmail.com>

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/ini_lookup.html