community.general.binary_file lookup – Read binary file and return it Base64 encoded
Note
This lookup plugin is part of the community.general collection (version 12.6.1).
You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install community.general.
To use it in a playbook, specify: community.general.binary_file.
New in community.general 11.2.0
Synopsis
- This lookup returns the contents from a file on the Ansible controller’s file system.
- The file is read as a binary file and its contents are returned Base64 encoded. This is similar to using ansible.builtin.file combined with ansible.builtin.b64encode, except that ansible.builtin.file does not support binary files as it interprets the contents as UTF-8, which can cause the wrong content being Base64 encoded.
Terms
Parameter | Comments |
|---|---|
Terms list / elements=string / required | Paths of the files to read. Relative paths will be searched for in different places. See Ansible task paths for more details. |
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('community.general.binary_file', key1=value1, key2=value2, ...) and query('community.general.binary_file', key1=value1, key2=value2, ...)
Parameter | Comments |
|---|---|
not_exist string | Determine how to react if the specified file cannot be found. Choices:
|
Notes
Note
- When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters:
lookup('community.general.binary_file', term1, term2, key1=value1, key2=value2)andquery('community.general.binary_file', term1, term2, key1=value1, key2=value2) - This lookup does not understand ‘globbing’ - use the ansible.builtin.fileglob lookup instead.
See Also
See also
- ansible.builtin.b64decode filter plugin
-
The b64decode filter can be used to decode Base64 encoded data. Note that Ansible cannot handle binary data, the data will be interpreted as UTF-8 text!
- ansible.builtin.file lookup plugin
-
You can use this lookup plugin to read text files from the Ansible controller.
- ansible.builtin.slurp
-
Also allows to read binary files Base64 encoded, but from remote targets. With
delegate_to: localhostcan be redirected to run on the controller, but you have to know the path to the file to read. Both this plugin and ansible.builtin.file use some search path logic to for example also find files in thefilesdirectory of a role. - Task paths
-
Search paths used for relative files.
Examples
---
- name: Output Base64 contents of binary files on screen
ansible.builtin.debug:
msg: "Content: {{ lookup('community.general.binary_file', item) }}"
loop:
- some-binary-file.bin
Return Value
Key | Description |
|---|---|
Return value list / elements=string |
Collection links
© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/community/general/binary_file_lookup.html
