[초급] 파이썬 파일 입출력, 지긋지긋한 한글 인코딩 박살내는 법

결론부터 말한다. encoding=’utf-8′. 이거 하나면 대부분 끝난다.

그런데도 왜 자꾸 ‘UnicodeDecodeError: ‘cp949′ codec can’t decode byte…’ 이딴 에러가 터지는가. 그건 당신 잘못이 아니다. 정확히는 윈도우(Windows)라는 운영체제 환경 탓이 크다.

이건 마치 해외 직구한 가전제품 플러그(UTF-8)가 우리나라 콘센트(CP949)에 안 맞는 것과 같은 이치다. 파이썬은 국제 표준인 UTF-8을 기본으로 생각하는데, 당신의 윈도우 PC는 아직도 구시대 유물인 CP949를 고집하고 있기 때문이다. 이 둘의 규격이 안 맞으니 글자가 깨지고 에러가 터지는 거다. 아주 간단한 원리.

이 문제를 해결하려고 구글링하면 온갖 복잡한 해결책이 나온다. 다 필요 없다. 핵심은 딱 하나. ‘데이터가 들어오고 나가는 모든 파이프라인의 인코딩 규격을 UTF-8로 통일한다.’ 이것만 머리에 넣으면 된다.

Q. 그냥 open() 함수만 쓰면 안 되는가?

A. 안된다. 윈도우 환경에서 파이썬의 open() 함수를 그냥 호출하면, 운영체제의 기본 인코딩인 ‘cp949’로 파일을 읽으려고 시도한다. 파일이 애초에 UTF-8로 저장되어 있었다면 여기서 바로 충돌이 발생한다. ‘나는 미국인(UTF-8)인데 왜 자꾸 한국어(CP949)로 말을 거냐’며 시스템이 비명을 지르는 셈이다.

Q. 그럼 무조건 encoding=’utf-8’만 붙이면 만사 해결인가?

A. 90%는 맞다. 하지만 10%의 예외가 존재한다. 애초에 당신이 다루려는 파일(.csv, .txt) 자체가 ‘ANSI’나 ‘EUC-KR’ 같은 더 낡은 방식으로 저장된 경우다. 이럴 땐 당연히 해당 인코딩으로 먼저 열어서 내용을 읽고, 저장할 때 UTF-8로 바꿔줘야 한다.

😭 초심자가 100% 확률로 저지르는 실수 3가지

이론은 쉽다. 실전에서 다들 망가지는 이유는 따로 있다. 직장인 열에 아홉은 여기서 막힌다. 나도 그랬다.

1. 읽을 때만 인코딩 지정하고, 쓸 때는 까먹는다.

문제 상황: pd.read_csv('data.csv', encoding='cp949') 로 데이터는 잘 읽어왔다. 신나게 데이터를 가공한 뒤 df.to_csv('result.csv') 로 저장했더니, 결과 파일의 한글이 다 깨져있다.

원인과 해결책: 읽을 때 사용한 인코딩과 쓸 때 사용한 인코딩이 달라서 그렇다. 들어오는 물(cp949)은 정수 처리했는데, 나가는 물(기본값)은 처리 안 한 꼴이다. 나갈 때도 규격을 명확히 지정해야 한다. df.to_csv('result.csv', encoding='utf-8-sig', index=False) 이렇게. 특히 엑셀에서 한글이 깨지지 않게 하려면 ‘utf-8’이 아니라 ‘utf-8-sig’를 쓰는 게 정신건강에 이롭다. 기억해둘 것.

2. 파일 경로에 한글이 포함된 경우.

문제 상황: open('C:/Users/파이프마스터/바탕화면/자료.txt') 처럼 파일 경로에 한글이 있으면 인코딩을 잘 맞춰도 에러가 나는 경우가 있다.

원인과 해결책: 파일 ‘내용’의 인코딩과 파일 ‘경로’의 인코딩은 다른 문제다. 시스템이 경로 자체를 해석하지 못하는 경우다. 가장 좋은 해결책은 처음부터 파일 경로나 파일명에 한글을 쓰지 않는 것이다. 이건 그냥 시스템 구축의 기본 원칙이다. ‘C:/data/project/raw_data.csv’ 이런 식으로 영어, 숫자, 언더바(_)만 사용해서 경로를 관리하는 습관을 들여야 한다. 근본적인 해결책임.

3. 눈에 보이지 않는 문자(BOM) 때문에 터지는 에러.

문제 상황: 분명히 UTF-8 파일이고, 코드는 encoding='utf-8' 로 완벽하게 짰는데 첫 줄을 읽어올 때 이상한 글자가 깨지거나 에러가 발생한다.

원인과 해결책: 이건 ‘BOM(Byte Order Mark)’이라는 눈에 보이지 않는 표식 때문이다. 특히 윈도우 메모장에서 UTF-8로 저장하면 파일 맨 앞에 이 표식이 몰래 숨어 들어간다. 일종의 꼬리표 같은 건데, 파이썬이 이걸 일반 글자로 착각해서 문제가 생긴다. 해결책은 간단하다. encoding='utf-8-sig' 를 사용하면 된다. ‘sig’가 바로 이 BOM을 알아서 처리하고 무시하라는 신호다. 데이터를 읽을 때 encoding='utf-8-sig'를 먼저 시도하고, 안되면 encoding='utf-8'로 읽는 것이 실전 팁이다.

결론은 심플하다. 읽고 쓸 때 모두 encoding='utf-8-sig'를 기본으로 박아두고, 경로에는 한글을 쓰지 않는다. 이것만 지켜도 당신의 자동화 파이프라인에서 인코딩 에러가 터질 확률은 99% 감소한다.

PipeMaster-Lab 운영정책 및 제보 안내