W3cubDocs

/Ansible 2.10

community.general.read_csv – Read a CSV file

Note

This plugin is part of the community.general collection.

To install it use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.read_csv.

Synopsis
Parameters
Notes
Examples
Return Values

Synopsis

Read a CSV file and return a list or a dictionary, containing one dictionary per row.

Parameters

Parameter	Choices/Defaults	Comments
delimiter string		A one-character string used to separate fields. When using this parameter, you change the default value used by `dialect`. The default value depends on the dialect used.
dialect string	Default: "excel"	The CSV dialect to use when parsing the CSV file. Possible values include `excel`, `excel-tab` or `unix`.
fieldnames list / elements=string		A list of field names for every column. This is needed if the CSV does not have a header.
key string		The column name used as a key for the resulting dictionary. If `key` is unset, the module returns a list of dictionaries, where each dictionary is a row in the CSV file.
path path / required		The CSV filename to read data from. aliases: filename
skipinitialspace boolean	Choices: no yes	Whether to ignore any whitespaces immediately following the delimiter. When using this parameter, you change the default value used by `dialect`. The default value depends on the dialect used.
strict boolean	Choices: no yes	Whether to raise an exception on bad CSV input. When using this parameter, you change the default value used by `dialect`. The default value depends on the dialect used.
unique boolean	Choices: no yes ←	Whether the `key` used is expected to be unique.

Notes

Note

Ansible also ships with the csvfile lookup plugin, which can be used to do selective lookups in CSV files from Jinja.

Examples

# Example CSV file with header
#
#   name,uid,gid
#   dag,500,500
#   jeroen,501,500

# Read a CSV file and access user 'dag'
- name: Read users from CSV file and return a dictionary
  community.general.read_csv:
    path: users.csv
    key: name
  register: users
  delegate_to: localhost

- ansible.builtin.debug:
    msg: 'User {{ users.dict.dag.name }} has UID {{ users.dict.dag.uid }} and GID {{ users.dict.dag.gid }}'

# Read a CSV file and access the first item
- name: Read users from CSV file and return a list
  community.general.read_csv:
    path: users.csv
  register: users
  delegate_to: localhost

- ansible.builtin.debug:
    msg: 'User {{ users.list.1.name }} has UID {{ users.list.1.uid }} and GID {{ users.list.1.gid }}'

# Example CSV file without header and semi-colon delimiter
#
#   dag;500;500
#   jeroen;501;500

# Read a CSV file without headers
- name: Read users from CSV file and return a list
  community.general.read_csv:
    path: users.csv
    fieldnames: name,uid,gid
    delimiter: ';'
  register: users
  delegate_to: localhost

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Returned	Description
dict dictionary	success	The CSV content as a dictionary. Sample: {'dag': {'gid': 500, 'name': 'dag', 'uid': 500}, 'jeroen': {'gid': 500, 'name': 'jeroen', 'uid': 501}}
list list / elements=string	success	The CSV content as a list. Sample: [{'gid': 500, 'name': 'dag', 'uid': 500}, {'gid': 500, 'name': 'jeroen', 'uid': 501}]

Authors

Dag Wieers (@dagwieers)

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/community/general/read_csv_module.html