community.general.read_csv module – Read a CSV file

Note

This module is part of the community.general collection (version 6.6.2).

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.read_csv.

Synopsis

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

Parameters

Parameter

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

The CSV dialect to use when parsing the CSV file.

Possible values include excel, excel-tab or unix.

Default: "excel"

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

aliases: filename

path / required

The CSV filename to read data from.

skipinitialspace

boolean

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.

Choices:

  • false

  • true

strict

boolean

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.

Choices:

  • false

  • true

unique

boolean

Whether the key used is expected to be unique.

Choices:

  • false

  • true ← (default)

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

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

Description

dict

dictionary

The CSV content as a dictionary.

Returned: success

Sample: {"dag": {"gid": 500, "name": "dag", "uid": 500}, "jeroen": {"gid": 500, "name": "jeroen", "uid": 501}}

list

list / elements=string

The CSV content as a list.

Returned: success

Sample: [{"gid": 500, "name": "dag", "uid": 500}, {"gid": 500, "name": "jeroen", "uid": 501}]

Authors

  • Dag Wieers (@dagwieers)