read_csv – Read a CSV file

New in version 2.8.

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
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
  read_csv:
    path: users.csv
    key: name
  register: users
  delegate_to: localhost

- 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
  read_csv:
    path: users.csv
  register: users
  delegate_to: localhost

- 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
  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': {'name': 'dag', 'uid': 500, 'gid': 500}, 'jeroen': {'name': 'jeroen', 'uid': 501, 'gid': 500}}
list
list
 success
The CSV content as a list.

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


Status

Authors

  • Dag Wieers (@dagwieers)

Hint

If you notice any issues in this documentation you can edit this document to improve it.