[Pandas] read_csv / to_csv

정의

pandas.read_csv 는 CSV(Comma-Separated Values) 또는 구분자 기반 텍스트 파일을 DataFrame 으로 읽는 함수. pandas 사용의 출발점.

반대 방향은 DataFrame.to_csv : DataFrame 을 CSV 로 내보내기.

사용 상황

read_csv 파이프라인

flowchart LR
    A["CSV 파일"] --> B["read_csv()"]
    B --> C["usecols: 컬럼 필터"]
    C --> D["dtype: 타입 변환"]
    D --> E["parse_dates: 날짜 파싱"]
    E --> F["na_values: NA 치환"]
    F --> G["DataFrame"]

기본 사용

import pandas as pd

df = pd.read_csv('data.csv')
df.to_csv('out.csv', index=False)

핵심 옵션 전체

구분자 / 인코딩

# TSV (탭 구분)
df = pd.read_csv('data.tsv', sep='\t')

# 한글 Windows 인코딩
df = pd.read_csv('korean.csv', encoding='cp949')

# BOM 있는 UTF-8 (Excel 저장)
df = pd.read_csv('excel.csv', encoding='utf-8-sig')

usecols + dtype (메모리 절약)

import io, pandas as pd
​
csv_text = """id,name,age,salary,notes
1,Alice,30,3000,manager
2,Bob,25,4500,engineer
3,Charlie,35,6000,director"""
​
df = pd.read_csv(
  io.StringIO(csv_text),
  usecols=['id', 'name', 'age'],
  dtype={'id': 'int32', 'age': 'int8'},
)
print(df)
print(df.dtypes.to_dict())

   id     name  age
0   1    Alice   30
1   2      Bob   25
2   3  Charlie   35
{'id': dtype('int32'), 'name': dtype('O'), 'age': dtype('int8')}

usecols 로 불필요한 컬럼 제외, dtype 으로 정수 크기 최소화.

dtype 최적화

df = pd.read_csv('data.csv', dtype={
    'id':       'int32',     # int64 대신 절반 메모리
    'age':      'int8',      # -128~127 범위면 충분
    'score':    'float32',   # float64 대신 절반
    'category': 'category',  # 문자열 반복이 많으면 category
})

parse_dates

# 단일 컬럼
df = pd.read_csv('events.csv', parse_dates=['created_at'])

# 여러 컬럼 → datetime
df = pd.read_csv('events.csv', parse_dates=['start', 'end'])

# 여러 컬럼 합쳐서 하나의 datetime 생성
df = pd.read_csv('events.csv', parse_dates={'datetime': ['date', 'time']})

na_values

df = pd.read_csv('data.csv', na_values=['', 'NULL', 'N/A', '-', 'none', 'nan'])

# 기본 NA 인식 목록을 끄고 직접 지정
df = pd.read_csv('data.csv',
    na_values=['-'],
    keep_default_na=False,
)

chunksize (대용량 스트리밍)

total_sales = 0
chunks_processed = 0

for chunk in pd.read_csv('huge.csv', chunksize=100_000):
    total_sales += chunk['amount'].sum()
    chunks_processed += 1

print(f'청크 {chunks_processed} 개 처리, 총 매출: {total_sales:,.0f}')

chunksize 를 지정하면 TextFileReader iterator 를 반환. 메모리에 전체를 올리지 않음.

low_memory

# 기본 low_memory=True: 컬럼 타입을 청크별로 추론 → 혼합 타입 DtypeWarning 가능
df = pd.read_csv('data.csv')

# low_memory=False: 전체를 한 번에 읽어 타입 결정 → 메모리 더 씀, 경고 없음
df = pd.read_csv('data.csv', low_memory=False)

# 가장 좋은 방법: dtype 명시
df = pd.read_csv('data.csv', dtype={'id': str, 'code': str})

pyarrow engine (pandas 2.0+)

# C 엔진보다 최대 수배 빠름
df = pd.read_csv('data.csv', engine='pyarrow')

# dtype_backend='pyarrow': Arrow 배열로 저장 (메모리 효율)
df = pd.read_csv('data.csv', engine='pyarrow', dtype_backend='pyarrow')

Arrow 기반 dtype 은 nullable int, string 등을 네이티브로 지원.

flowchart LR
    A["read_csv engine 선택"] --> B["c (기본)"]
    A --> C["python"]
    A --> D["pyarrow (pandas 2.0+)"]
    B --> E["빠름, 대부분 상황"]
    C --> F["유연, 복잡한 포맷"]
    D --> G["가장 빠름, Arrow 타입"]

to_csv (저장)

# 기본 (index 제외)
df.to_csv('out.csv', index=False)

# 한글 Excel 호환 (BOM)
df.to_csv('out.csv', encoding='utf-8-sig', index=False)

# TSV
df.to_csv('out.tsv', sep='\t', index=False)

# gzip 압축 (자동 감지)
df.to_csv('out.csv.gz', compression='gzip', index=False)

# 일부 컬럼만
df.to_csv('out.csv', columns=['id', 'name', 'age'], index=False)

# 날짜 포맷
df.to_csv('out.csv', date_format='%Y-%m-%d', index=False)

함정

1. index 가 CSV 에 포함됨

df.to_csv('out.csv')               # 0,1,2... 열이 앞에 생김
df.to_csv('out.csv', index=False)  # ✓

저장 후 다시 읽으면 Unnamed: 0 컬럼이 생기는 현상의 원인.

2. 정수 컬럼이 float 으로 변환

NaN 이 하나라도 있으면 정수를 float 으로 저장 (NaN 이 float 타입). 해법:

# pandas 1.0+ nullable integer
df['col'] = df['col'].astype('Int64')   # 대문자 I, nullable int
pd.read_csv('data.csv', dtype={'col': 'Int64'})

3. DtypeWarning: mixed types

# 컬럼에 숫자와 문자가 섞이면
# DtypeWarning: Columns (N) have mixed types
df = pd.read_csv('data.csv', dtype={'mixed_col': str})   # str 로 통일
# 또는
df = pd.read_csv('data.csv', low_memory=False)

4. 한글 깨짐

5. 대용량 파일 메모리 폭주

# ❌ 10GB 한 번에
df = pd.read_csv('10gb.csv')

# ✓ 청크 스트리밍
for chunk in pd.read_csv('10gb.csv', chunksize=50_000):
    process(chunk)

# ✓ usecols 로 컬럼 최소화
df = pd.read_csv('10gb.csv', usecols=['id', 'amount'], dtype={'amount': 'float32'})

6. skiprows 와 header 혼동

# 처음 2 행 건너뛰고 3 번째 행을 헤더로
df = pd.read_csv('data.csv', skiprows=2)

# 처음 2 행 건너뛰고 헤더도 없음
df = pd.read_csv('data.csv', skiprows=2, header=None, names=['a', 'b', 'c'])

참고

• Pandas DataFrame
• Pandas read_excel
• Pandas read_json
• Pandas read_parquet
• Pandas Nullable Types
• Pandas 성능 / 메모리 최적화
• Pandas pyarrow backend