Skip to content
Tutorials Center
My learning

Topics

Lesson 64 of 149 Β· Files and Errors

CSV Files

Read and write CSV files in Python with csv.reader, csv.writer, DictReader and DictWriter. Learn about quoting, delimiters, headers and number conversion.

CSV (comma-separated values) is the most common way to move tables of data between programs. Spreadsheets export it, databases import it, and countless public datasets are published as CSV. Each line is a row, and commas separate the columns:

TEXT
name,city,age
Ana,Porto,34
Ben,Oslo,27

It looks so simple that it's tempting to just call line.split(","). That works until a value contains a comma itself, like "Smith, Jr.", or a line break inside quotes. Python's built-in csv module handles all of those rules for you. In this lesson you'll read and write CSV files as lists and as dictionaries, and learn the handful of options that matter in practice.

Note: as in Reading and Writing Files, the editors here use an in-memory file system that resets on every run, so each example writes its CSV file first and then reads it.

Why not just split on commas?

Here's a small file where one value contains a comma. CSV handles that by wrapping the value in double quotes. Compare a naive split with the csv module:

Python split() versus csv.reader

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.

The naive split breaks "Smith, Jr." into two pieces and keeps the quote marks. csv.reader understands the quoting and gives you exactly two columns per row.

Tip: whenever you hand a file to the csv module, open it with newline="". The csv module manages line endings itself, and this setting stops Python from translating them first. Without it, you can get blank rows between your data on Windows, and quoted values that contain line breaks can be read incorrectly.

Reading rows with csv.reader

csv.reader(file) returns an iterator that gives you each row as a list of strings. The header is just the first row, so a common pattern is to pull it out with next() and then loop over the rest:

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

Notice the conversions: float(price) and int(quantity). CSV has no types. Every value comes back as a string, and it's your job to convert numbers, dates and booleans. If a value can't be converted, float() or int() raises ValueError, which you'll learn to handle in Exceptions and try/except.

Unpacking each row into named variables (for product, price, quantity in reader) makes the loop easy to read, but it only works when every row has exactly that many columns.

Writing rows with csv.writer

To create a CSV file, wrap the file object in csv.writer() and call writerow() for one row or writerows() for many. The writer adds commas and line endings, and quotes any value that needs it:

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

Look at the output. The writer quoted "Washington, D.C." because of its comma, and it doubled the quotes inside "The ""Big Apple""", which is how CSV escapes a quote character. Numbers were converted to strings automatically. You never have to do any of this by hand. The writer also ends every row with \r\n, the line ending the CSV standard specifies; the example reads the file back without newline="" only to display it as plain text.

Rows as dictionaries: DictReader

Remembering that the price is column 1 and the quantity column 2 gets fragile as files grow. csv.DictReader uses the header row as keys and gives you each row as a dictionary, so you can write row["price"] instead of row[1]:

Python DictReader

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.

DictReader reads the first line as field names automatically. Your code keeps working even if someone adds a column or reorders the columns in the file, because you look values up by name. Note that list(reader) must run inside the with block: once the file is closed, the reader can't read any more rows.

If a file has no header line, pass the names yourself: csv.DictReader(file, fieldnames=["name", "grade", "score"]).

Writing dictionaries: DictWriter

csv.DictWriter is the mirror image. You tell it the column order with fieldnames, call writeheader() once, and then write dictionaries:

Python DictWriter

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.

Two DictWriter details are worth knowing:

  • If a dictionary is missing a field, that cell is written empty. You can change the filler with restval="n/a".
  • If a dictionary has an extra key that isn't in fieldnames, DictWriter raises ValueError. Pass extrasaction="ignore" to silently skip extra keys instead.

Other delimiters and dialects

Not every "CSV" uses commas. Many European spreadsheets export with semicolons because the comma is their decimal separator, and TSV files use tabs. Both the readers and the writers accept a delimiter argument:

Python
reader = csv.reader(file, delimiter=";")
writer = csv.writer(file, delimiter="\t")

You can also control quoting. quoting=csv.QUOTE_ALL wraps every value in quotes, and quoting=csv.QUOTE_NONNUMERIC quotes text only. When reading with QUOTE_NONNUMERIC, unquoted values are converted to float for you.

When you don't know a file's format in advance, csv.Sniffer().sniff(sample) can guess the delimiter from a sample of text. It's a guess, though, so prefer explicit settings when you know the source.

Watch out: a CSV file exported from a spreadsheet may start with an invisible byte order mark (BOM). It shows up as a strange first column name like ο»Ώname. Open such files with encoding="utf-8-sig" to strip it automatically.

Check your understanding

Quick check Β· 5 questions

of 5 answered You scored / 5 Β· perfect!

  1. 1. Why should you use the csv module instead of line.split(",")?

    Real CSV data quotes values that contain special characters. The csv module understands these rules; a plain split() does not.
  2. 2. What type is row["age"] when you read a row with DictReader?

    CSV has no data types, so every value comes back as a string. Convert it with int() or float() yourself.
  3. 3. Which argument should you pass to open() when working with CSV files?

    newline="" lets the csv module handle line endings itself, which avoids blank rows on Windows and broken multi-line values.
  4. 4. What does DictWriter do with a dictionary that has a key not listed in fieldnames?

    By default DictWriter refuses unexpected keys with ValueError. extrasaction="ignore" tells it to drop them.
  5. 5. How do you read a file whose columns are separated by semicolons?

    Both readers and writers take a delimiter argument. Use delimiter="\t" for tab-separated files.

Summary

  • Use the csv module, not split(","), so quoted values with commas, quotes or line breaks work.
  • Open CSV files with newline="" and encoding="utf-8" (or "utf-8-sig" for spreadsheet exports with a BOM).
  • csv.reader gives rows as lists; csv.writer writes lists with writerow() and writerows().
  • DictReader and DictWriter work with dictionaries keyed by the header, which is easier to read and survives column changes.
  • Every value read from CSV is a string; convert numbers yourself.
  • delimiter= handles semicolons and tabs, and quoting= controls how values are quoted.

Next: Exceptions and try/except, where you'll learn to handle errors like a missing file or a bad number without crashing.