Python의 UnicodeDecodeError 해결하기: cp949 코덱 오류

파이썬/Basic

Python의 UnicodeDecodeError 해결하기: cp949 코덱 오류

코샵 2025. 5. 9. 11:55

개발을 하다 보면 아래와 같은 오류 메시지를 만나본 적이 있을 것입니다:

UnicodeDecodeError: 'cp949' codec can't decode byte 0xec in position 9: illegal multibyte sequence

특히 Windows 환경에서 Python을 사용하는 한국 개발자들이 자주 마주치는 이 오류는 pip 패키지 설치나 파일 입출력 과정에서 발생하곤 합니다. 이번 글에서는 이 오류의 원인과 해결 방법을 상세히 알아보겠습니다.

오류의 원인: 인코딩 불일치

CP949란 무엇인가?

CP949(Code Page 949)는 Windows에서 한국어를 표현하기 위해 사용하는 인코딩 방식입니다. 다른 말로는 '확장완성형 한글 코드'라고도 불립니다. 이는 EUC-KR의 확장 버전으로, 더 많은 한글 문자를 표현할 수 있습니다.

오류 발생 원인

이 오류는 보통 다음과 같은 상황에서 발생합니다:

인코딩 불일치: UTF-8로 인코딩된 파일이나 문자열을 CP949로 해석하려 할 때
비 ASCII 문자: 파일 경로나 패키지 이름에 한글이나 다른 비 ASCII 문자가 포함되어 있을 때
Windows 기본 설정: Windows에서 Python은 기본적으로 시스템 기본 인코딩(한국어 Windows의 경우 CP949)을 사용합니다

pip 설치 과정에서 이 오류가 발생하는 것은 패키지 정보나 설치 경로에 한글이 포함되어 있거나, 패키지 내부의 파일이 UTF-8로 인코딩되어 있는데 이를 CP949로 해석하려고 시도하기 때문입니다.

해결 방법

1. Python 명령어에 인코딩 옵션 추가

가장 간단한 해결 방법은 Python 실행 시 인코딩을 명시적으로 지정하는 것입니다:

# CMD에서
set PYTHONIOENCODING=utf-8
pip install 패키지명

# PowerShell에서
$env:PYTHONIOENCODING="utf-8"
pip install 패키지명

2. pip 명령어에 직접 옵션 추가

pip install 패키지명 --no-cache-dir

--no-cache-dir 옵션은 캐시된 파일을 사용하지 않고 새로 다운로드하므로, 손상된 캐시 파일로 인한 문제를 방지할 수 있습니다.

3. 가상 환경 사용

가상 환경을 사용하면 시스템 설정과 분리된 Python 환경을 만들 수 있어 이런 인코딩 문제를 줄일 수 있습니다:

# 가상 환경 생성
python -m venv myenv

# 가상 환경 활성화 (Windows)
myenv\Scripts\activate

# 패키지 설치
pip install 패키지명

4. PYTHONLEGACYWINDOWSSTDIO 환경 변수 설정

Windows에서 Python 3.6 이상 버전을 사용한다면, 다음 환경 변수를 설정하는 것이 도움이 될 수 있습니다:

# CMD에서
set PYTHONLEGACYWINDOWSSTDIO=1
pip install 패키지명

# PowerShell에서
$env:PYTHONLEGACYWINDOWSSTDIO=1
pip install 패키지명

5. 영어 Windows 계정 사용

근본적인 해결책은 아니지만, Windows 사용자 계정 이름이 한글인 경우 영어 계정으로 변경하거나 영어 계정을 새로 만들어 사용하는 것도 방법입니다.

6. 소스 코드에서 파일 열 때 인코딩 지정

파일을 다룰 때는 항상 인코딩을 명시적으로 지정하는 것이 좋습니다:

# 파일 읽기
with open('파일명.txt', 'r', encoding='utf-8') as f:
    content = f.read()

# 파일 쓰기
with open('파일명.txt', 'w', encoding='utf-8') as f:
    f.write(content)

7. 시스템 기본 인코딩 변경

Windows에서 시스템 기본 인코딩을 변경하는 방법도 있지만, 이 방법은 다른 시스템에 영향을 줄 수 있으므로 신중하게 사용해야 합니다:

제어판 > 시계 및 국가 > 국가 또는 지역 > 관리 탭 > 시스템 로캘 변경
"Beta: 세계 언어 지원을 위해 Unicode UTF-8 사용" 옵션 체크
컴퓨터 재시작

각 Python 버전별 주의사항

Python 버전에 따라 인코딩 처리 방식이 다르므로, 버전별 특징을 알아두면 도움이 됩니다:

Python 2.x

Python 2.x에서는 기본적으로 ASCII를 사용하며, 한글과 같은 유니코드 문자를 처리하려면 명시적으로 인코딩을 지정해야 합니다:

# Python 2.x
# 파일 상단에 추가
# -*- coding: utf-8 -*-

# 문자열 앞에 u 접두사 사용
text = u'안녕하세요'

Python 3.x

Python 3.x에서는 기본적으로 UTF-8을 사용하지만, Windows 환경에서는 여전히 cp949 관련 문제가 발생할 수 있습니다:

# Python 3.x
# 기본적으로 문자열은 유니코드입니다
text = '안녕하세요'

# 파일 처리 시 인코딩 명시 필요
with open('file.txt', 'r', encoding='utf-8') as f:
    content = f.read()

실전 문제 해결 시나리오

시나리오 1: pip 설치 중 오류

UnicodeDecodeError: 'cp949' codec can't decode byte 0xec in position 9: illegal multibyte sequence

해결 과정:

명령 프롬프트를 관리자 권한으로 실행
환경 변수 설정:
```
set PYTHONIOENCODING=utf-8
```
pip 캐시 비우기:
```
pip cache purge
```

패키지 재설치:

pip install 패키지명 --no-cache-dir

시나리오 2: 한글이 포함된 CSV 파일 읽기 오류

# 오류 발생 코드
df = pd.read_csv('한글데이터.csv')

# 오류 메시지
UnicodeDecodeError: 'cp949' codec can't decode byte 0xec in position...

해결 코드:

# 인코딩 명시적 지정
df = pd.read_csv('한글데이터.csv', encoding='utf-8')

# 만약 위 방법이 작동하지 않는다면 다른 인코딩 시도
df = pd.read_csv('한글데이터.csv', encoding='euc-kr')

시나리오 3: 웹 스크래핑 데이터 저장 오류

# 오류 발생 코드
import requests
from bs4 import BeautifulSoup

response = requests.get('https://example.com')
soup = BeautifulSoup(response.text, 'html.parser')

with open('결과.txt', 'w') as f:
    f.write(str(soup))

# 오류 메시지
UnicodeEncodeError: 'cp949' codec can't encode character...

해결 코드:

with open('결과.txt', 'w', encoding='utf-8') as f:
    f.write(str(soup))

프로젝트 설정에 인코딩 표준화하기

프로젝트 전체에 인코딩 표준을 적용하면 이러한 문제를 최소화할 수 있습니다:

1. .gitattributes 파일 생성

# 모든 텍스트 파일 UTF-8로 처리
* text=auto eol=lf encoding=utf-8
*.py text eol=lf encoding=utf-8

2. VSCode 설정 (settings.json)

{
    "files.encoding": "utf8",
    "files.autoGuessEncoding": true,
    "python.terminal.activateEnvironment": true
}

3. PyCharm 설정

File > Settings > Editor > File Encodings
Global Encoding과 Project Encoding을 UTF-8로 설정
Properties Files도 UTF-8로 설정

4. 프로젝트 표준 문서화

README.md나 CONTRIBUTING.md 파일에 프로젝트의 인코딩 표준을 명시하여 모든 기여자가 동일한 규칙을 따르도록 합니다.

결론

UnicodeDecodeError: 'cp949' codec can't decode byte... 오류는 Windows 환경에서 한글과 같은 유니코드 문자를 처리할 때 자주 발생하는 문제입니다. 이 문제는 주로 인코딩 불일치 때문에 발생하며, 명시적으로 인코딩을 지정하는 것이 가장 확실한 해결책입니다.

프로젝트 초기부터 UTF-8을 표준 인코딩으로 설정하고, 파일 입출력이나 외부 리소스 접근 시 항상 인코딩을 명시하는 습관을 들이면 이러한 문제를 크게 줄일 수 있습니다.

Python 개발 시 인코딩 문제로 더 이상 고생하지 마시고, 이 글에서 소개한 방법들을 적용하여 원활한 개발 환경을 구축하시기 바랍니다.

저작자표시 비영리 변경금지 (새창열림)