record my life

파이썬 CSV 한글 깨짐 해결 방법

파이썬으로 CSV 파일을 읽다가 한글이 깨지거나 UnicodeDecodeError가 뜨면 정말 당황스럽죠.

저도 처음에는 왜 파일은 멀쩡한데 파이썬에서만 오류가 나는지 헷갈렸는데, 알고 보면 대부분 인코딩 방식이 맞지 않아서 생기는 문제였어요.

이번 글에서는 파이썬 CSV 한글 깨짐, UnicodeDecodeError 해결, 그리고 cp949 / utf-8 차이까지 한 번에 정리해볼게요.

왜 이런 오류가 생길까?

CSV 파일은 겉으로 보기에는 그냥 텍스트 파일이지만, 실제로는 어떤 방식으로 문자를 저장했는지가 중요해요.

• utf-8: 웹이나 개발 환경에서 가장 많이 사용하는 인코딩
• cp949: 윈도우 환경, 특히 한글 CSV에서 자주 나오는 인코딩
• euc-kr: 예전 한글 문서에서 종종 보이는 인코딩

즉, 파일은 cp949로 저장되어 있는데 파이썬에서 utf-8로 읽으려고 하면 오류가 납니다.

대표적인 오류 메시지

UnicodeDecodeError: 'utf-8' codec can't decode byte ...

이 에러는 보통 utf-8이 아닌 파일을 utf-8로 읽었을 때 발생합니다.

가장 먼저 해볼 해결 방법

pandas로 CSV를 읽는다면 encoding 옵션을 직접 넣어보세요.

import pandas as pd

df = pd.read_csv("data.csv", encoding="cp949")
print(df.head())

만약 이 방법으로 잘 열리면 파일이 cp949 계열이었다는 뜻입니다.

utf-8 파일이라면?

import pandas as pd

df = pd.read_csv("data.csv", encoding="utf-8")
print(df.head())

간혹 UTF-8 BOM 때문에 문제가 생기는 경우도 있어서 이럴 때는 아래처럼 해보면 됩니다.

import pandas as pd

df = pd.read_csv("data.csv", encoding="utf-8-sig")
print(df.head())

open()으로 파일을 읽을 때도 똑같아요

with open("data.csv", "r", encoding="cp949") as f:
    text = f.read()
    print(text)

read_csv()든 open()이든 핵심은 같습니다. 파일의 실제 인코딩과 코드에서 지정한 인코딩을 맞추는 것이에요.

cp949와 utf-8 중 뭘 쓰면 될까?

• 엑셀에서 저장한 한글 CSV: cp949 먼저 시도
• 웹에서 내려받은 데이터나 개발용 파일: utf-8 먼저 시도
• UTF-8인데도 이상하면: utf-8-sig 확인

실전에서 가장 많이 쓰는 코드

import pandas as pd

try:
    df = pd.read_csv("data.csv", encoding="utf-8")
except UnicodeDecodeError:
    df = pd.read_csv("data.csv", encoding="cp949")

print(df.head())

이렇게 작성하면 utf-8로 먼저 읽고, 안 되면 cp949로 다시 읽을 수 있어서 실무에서도 꽤 편리해요.

한글이 깨질 때 체크할 것

• 파일을 어느 프로그램에서 저장했는지 확인하기
• 엑셀 저장 파일이면 cp949 가능성 먼저 보기
• 웹/개발 도구에서 만든 파일이면 utf-8 확인하기
• utf-8-sig도 같이 테스트해보기

정리

파이썬 CSV 한글 깨짐 문제는 대부분 인코딩 mismatch 때문에 생깁니다.

가장 많이 쓰는 해결 순서는 아래처럼 생각하면 편해요.

1. utf-8로 시도한다
2. 안 되면 cp949로 시도한다
3. 그래도 이상하면 utf-8-sig를 확인한다

저처럼 처음에 인코딩 때문에 시간을 많이 쓰는 분들께 도움이 되었으면 좋겠어요. 다음에는 pandas read_csv 자주 나는 오류도 정리해보겠습니다.

함께 보면 좋은 글

파이썬에서 문자열, 인코딩, 파일 입출력을 같이 이해해두면 이런 오류를 훨씬 빨리 해결할 수 있어요.