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
|
|
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
|
|
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
|
|
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
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Dag Wieers (@dagwieers)
Hint
If you notice any issues in this documentation, you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/modules/read_csv_module.html