csv.excel

Readers and writers use excel unless told otherwise. excel_tab only changes the delimiter to a tab; unix_dialect ends lines with \n and quotes every field. Class names use underscores, registry names use hyphens: excel_tab is 'excel-tab', unix_dialect is 'unix'.

csv classesPython 2.3+ (unix_dialect: 3.2+)Live demo
Common call
csv.writer(f, dialect='unix')
Returns
excel: 'a,b\r\n' · excel-tab: 'a\tb\r\n' · unix: '"a","b"\n'
Replaces
spelling out delimiter=, lineterminator=, quoting=
Watch out
the name is 'excel-tab' with a hyphen, the class excel_tab
class csv.excel · class csv.excel_tab · class csv.unix_dialect
→ class

Demo

Live evaluation
The same two rows written with a dialect name: 'excel', 'excel-tab', 'unix' (or anything else).
Try:
Inputs
namestra dialect name
Code
import csv, io
buf = io.StringIO(newline='')
w = csv.writer(buf, dialect='excel')
w.writerows([['id', 'note'], [1, 'say "hi"']])
buf.getvalue()
Result
'id,note\r\n1,"say ""hi"""\r\n'

unix quotes every field, including the number 1, and ends lines with \n; excel and excel-tab end them with \r\n. The class name excel_tab is not a registered name, so dialect='excel_tab' raises csv.Error: unknown dialect — pass the class itself (dialect=csv.excel_tab) or the hyphenated name. Reading comma text as excel-tab gives one field per line, quotes included, because the quote does not start the field.

Common patterns

Read a tab-separated file
dialect='excel-tab' is the same as delimiter='\t'.
import csv
with open('data.tsv', newline='', encoding='utf-8') as f:
    rows = list(csv.reader(f, dialect='excel-tab'))
Unix-style output
\n line endings and every field quoted.
import csv
with open('out.csv', 'w', newline='', encoding='utf-8') as f:
    csv.writer(f, dialect='unix').writerows(rows)
Base your own dialect on excel
Inherit the sensible defaults and override one attribute.
import csv

class SemicolonExcel(csv.excel):
    delimiter = ';'

Examples

1. excel settings
import csv (csv.excel.delimiter, csv.excel.quotechar, csv.excel.lineterminator, csv.excel.quoting)
Returns
(',', '"', '\r\n', 0)
2. excel_tab only changes the delimiter
import csv (csv.excel_tab.delimiter, csv.excel_tab.__bases__[0].__name__)
Returns
('\t', 'excel')
3. unix_dialect
import csv (csv.unix_dialect.lineterminator, csv.unix_dialect.quoting == csv.QUOTE_ALL)
Returns
('\n', True)
4. Pass the class directly
import csv, io buf = io.StringIO(newline='') csv.writer(buf, dialect=csv.excel_tab).writerow(['a', 'b']) buf.getvalue()
Returns
'a\tb\r\n'
5. Registered names
import csv csv.list_dialects()
Returns
['excel', 'excel-tab', 'unix']
6. They are csv.Dialect subclasses
import csv [issubclass(c, csv.Dialect) for c in (csv.excel, csv.excel_tab, csv.unix_dialect)]
Returns
[True, True, True]

Pitfalls

1. Using the class name as a string
The registry knows 'excel-tab' and 'unix', not the Python class names.
dialect='unix_dialect'
import csv, io
csv.writer(io.StringIO(), dialect='unix_dialect')
_csv.Error: unknown dialect
dialect='unix'
import csv, io
buf = io.StringIO(newline='')
csv.writer(buf, dialect='unix').writerow(['a', 1])
buf.getvalue()
'"a","1"\n'
2. Expecting excel to mean semicolons
Excel in many European locales saves CSV with semicolons, but the excel dialect is always comma-separated. Pass the delimiter.
dialect='excel'
import csv
next(csv.reader(['Name;Price', 'Tea;2,50'], dialect='excel'))
['Name;Price']
delimiter=';'
import csv
next(csv.reader(['Name;Price', 'Tea;2,50'], delimiter=';'))
['Name', 'Price']

When to use

Use it
  • excel: the default — files for and from spreadsheets
  • excel-tab: TSV files
  • unix: tools expecting \n line endings and quoted fields
Reach for something else
  • Semicolon CSV from European Excel → delimiter=";" (or your own dialect)

Notes

CPython impl
Lib/csv.py — class excel(Dialect), class excel_tab(excel), class unix_dialect(Dialect); each is registered at import: register_dialect('excel', excel), ('excel-tab', excel_tab), ('unix', unix_dialect)
escapechar
None in all three (inherited from csv.Dialect)
Version
unix_dialect was added in Python 3.2

FAQ

excel: comma delimiter, double-quote quotechar, doubled quotes inside fields, minimal quoting and \r\n line endings.