Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Files, Paths and Text I/O

The csv module

Reference for Python's csv module: reader, writer, DictReader, DictWriter, delimiters, quoting rules, newline='' and common CSV pitfalls.

CSV (comma-separated values) looks simple, but real files contain commas inside values, quotes, line breaks inside cells and different delimiters. The csv module handles all of that for you, so you should not split lines on "," yourself.

It offers four main tools: csv.reader and csv.writer work with lists of strings, csv.DictReader and csv.DictWriter work with dictionaries keyed by column name. All of them wrap a file object (or any iterable of lines).

Python
import csv

with open("people.csv", newline="", encoding="utf-8") as f:
    for row in csv.reader(f):
        print(row)

Try it

Python Writing and reading rows

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Dictionaries, delimiters and conversion

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Syntax

Python
csv.reader(csvfile, dialect="excel", **fmtparams)
csv.writer(csvfile, dialect="excel", **fmtparams)
csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect="excel", **fmtparams)
csv.DictWriter(f, fieldnames, restval="", extrasaction="raise", dialect="excel", **fmtparams)
Name Description
csvfile / f A file opened with newline="", or any iterable of strings (reader) or object with write() (writer).
delimiter Single character between fields; default ",". Use "\t" for TSV or ";" for many European exports.
quotechar Character that wraps fields containing special characters; default '"'.
quoting csv.QUOTE_MINIMAL (default), QUOTE_ALL, QUOTE_NONNUMERIC, QUOTE_NONE.
lineterminator Row ending written by writers; default "\r\n".
fieldnames Column names for the dict classes. DictReader takes them from the first row if omitted.
extrasaction DictWriter: "raise" (default) or "ignore" for dictionary keys not in fieldnames.

Writer methods: writerow(row), writerows(rows); DictWriter also has writeheader().

Return value: a reader yields one list of strings per row (a dict for DictReader; a plain dict since Python 3.8). A writer's writerow() returns what the underlying write() returned.

Raises: csv.Error for malformed input or bad arguments, ValueError from DictWriter for unknown keys, TypeError for invalid dialect parameters.

Usage notes

  • Open files with newline="". The module handles line endings itself. Without it, quoted cells containing newlines can break on read, and on Windows every row may get an extra blank line on write.
  • Everything is a string when reading. Convert numbers and dates yourself (int(row["stock"])). QUOTE_NONNUMERIC makes the reader convert unquoted values to float, but explicit conversion is clearer.
  • Writing converts with str(). None becomes an empty string, numbers become text, and QUOTE_NONNUMERIC quotes only non-numbers.
  • Empty lines read as an empty list [] with csv.reader, but DictReader skips them.
  • Short and long rows. DictReader fills missing values with restval (default None) and stores extra values as a list under restkey (default None).
  • Encoding. Pass encoding="utf-8". For files exported from Excel with a byte-order mark, use "utf-8-sig".
  • Detecting formats. csv.Sniffer().sniff(sample) can guess the delimiter, but it can be wrong; if you know the format, state it.
  • Large files. Readers are lazy, so a loop uses little memory. list(reader) loads everything.
  • When to use something else. For analysis, pandas.read_csv() is far more powerful. For nested data, JSON is a better fit.