Нашли ошибку?
базовыйpandas 3.0.6

Чтение CSV: read_csv

Прочитать CSV в таблицу с нужными разделителями, типами, датами и пропусками — и записать обратно.

Нужно знать:DataFrame

Содержание статьи

Коротко

  • pd.read_csv("файл.csv") читает таблицу; первая строка — заголовок, разделитель — запятая.
  • Типы столбцов определяются автоматически. Даты по умолчанию остаются строками — их разбирают через parse_dates.
  • Пустые поля и строки вроде NA, null становятся NaN; свои обозначения пропусков — na_values.
  • CSV из русского Excel: sep=";", decimal=",", иногда encoding="cp1251".
  • df.to_csv("файл.csv", index=False) — запись; без index=False индекс попадёт в файл лишним столбцом.

Синтаксис

pd.read_csv(path, sep=",", header="infer", names=None, index_col=None,
          usecols=None, dtype=None, parse_dates=None, na_values=None,
          nrows=None, skiprows=None, decimal=".", thousands=None,
          encoding="utf-8")
df.to_csv(path, index=False, sep=",", encoding="utf-8")

Параметры

ПараметрЧто делаетПо умолчанию
sepразделитель полей","
headerномер строки заголовка; None — заголовка нет0
namesсвои имена столбцовNone
index_colстолбец (имя или номер), который станет индексомNone
usecolsкакие столбцы читатьвсе
dtypeтипы столбцов: словарь {"столбец": тип}по данным
parse_datesсписок столбцов, которые разобрать как датыNone
na_valuesдополнительные обозначения пропусков: список или словарь по столбцамNone
nrows / skiprowsсколько строк прочитать / пропустить в началеNone
decimal / thousandsдесятичный разделитель и разделитель тысяч"." / None
encodingкодировка файла"utf-8"

Примеры

Данные для примеровиспользуются во всех примерах ниже
from pathlib import Path

Path("sales.csv").write_text(
    "date,city,cups,price\n"
    "2024-03-01,Омск,120,180.5\n"
    "2024-03-01,Тула,85,\n"
    "2024-03-02,Омск,132,181.0\n",
    encoding="utf-8",
)
Path("excel_ru.csv").write_text(      # так сохраняет CSV русский Excel
    "Город;Выручка\n"
    "Омск;1 250,50\n"
    "Тула;980,00\n",
    encoding="utf-8",
)
Прочитать файл
pd.read_csv("sales.csv")
Вывод
         date  city  cups  price
0  2024-03-01  Омск   120  180.5
1  2024-03-01  Тула    85    NaN
2  2024-03-02  Омск   132  181.0
Какие типы получились
pd.read_csv("sales.csv").dtypes
Вывод
date         str
city         str
cups       int64
price    float64
dtype: object
Только нужные столбцы и строки
pd.read_csv("sales.csv", usecols=["city", "cups"], nrows=2)
Вывод
   city  cups
0  Омск   120
1  Тула    85
Даты и индекс
df = pd.read_csv("sales.csv", parse_dates=["date"], index_col="date")
print(df.index.dtype)
df
Вывод
datetime64[us]
            city  cups  price
date
2024-03-01  Омск   120  180.5
2024-03-01  Тула    85    NaN
2024-03-02  Омск   132  181.0
CSV из русского Excel
pd.read_csv("excel_ru.csv", sep=";", decimal=",", thousands=" ")
Вывод
  Город  Выручка
0  Омск   1250.5
1  Тула    980.0
Свои имена столбцов
pd.read_csv("sales.csv", header=0, names=["день", "город", "чашки", "цена"])
Вывод
         день город  чашки   цена
0  2024-03-01  Омск    120  180.5
1  2024-03-01  Тула     85    NaN
2  2024-03-02  Омск    132  181.0
Свои обозначения пропусков
pd.read_csv("sales.csv", na_values={"cups": [85]})   # 85 считать пропуском
Вывод
         date  city   cups  price
0  2024-03-01  Омск  120.0  180.5
1  2024-03-01  Тула    NaN    NaN
2  2024-03-02  Омск  132.0  181.0
Записать CSV
df = pd.read_csv("sales.csv")
df.to_csv("out.csv", index=False)
print(Path("out.csv").read_text())
Вывод
date,city,cups,price
2024-03-01,Омск,120,180.5
2024-03-01,Тула,85,
2024-03-02,Омск,132,181.0

Подводные камни

Лишний столбец Unnamed: 0

По умолчанию to_csv записывает индекс. При повторном чтении он превращается в столбец без имени.

Запись с индексом
df = pd.read_csv("sales.csv")
df.to_csv("out.csv")                  # индекс записан первым столбцом
pd.read_csv("out.csv").columns
Вывод
Index(['Unnamed: 0', 'date', 'city', 'cups', 'price'], dtype='str')

Файл не в UTF-8

Старые файлы из Windows часто в кодировке cp1251. Передайте encoding="cp1251".

Чтение файла cp1251ошибка: UnicodeDecodeError
Path("win.csv").write_text("Город\nОмск\n", encoding="cp1251")
pd.read_csv("win.csv")                # по умолчанию ожидается UTF-8
Ошибка
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc3 in position 0: invalid continuation byte