# read_csv – Read a CSV file

New in version 2.8.

- Synopsis

- Parameters

- Notes

- Examples

- Return Values

- Status

## 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

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