Python 2.7에서 'ascii' codec can't encode characters 에러 해결하기

Python 2.7로 한글이 포함된 코드를 작성하다 보면 한 번쯤 마주치게 되는 에러가 있습니다.

UnicodeEncodeError: 'ascii' codec can't encode characters

오늘은 이 에러가 왜 발생하는지, 그리고 어떻게 해결할 수 있는지 알아보겠습니다.

---

원인: Python 2.7의 두 가지 문자열 타입

Python 2.7에서는 문자열 타입이 2가지로 나뉩니다.

타입	설명	예시
str	바이트 문자열 (기본값, ASCII만 지원)	'hello'
unicode	유니코드 문자열 (한글 등 지원)	u'안녕하세요'

'안녕하세요'   # str 타입 - 실제로는 UTF-8 바이트
u'안녕하세요'  # unicode 타입

겉보기엔 비슷해 보이지만, 내부적으로는 완전히 다른 방식으로 처리됩니다.

---

에러 발생 시점

문제는 str()이나 .format()에서 unicode → str 변환이 일어날 때 발생합니다. Python 2.7은 이 변환에 기본적으로 ASCII 코덱을 사용하는데, ASCII는 한글을 표현할 수 없기 때문에 에러가 발생하는 것입니다.

msg = u'안녕하세요'  # unicode 타입

# 이 순간 에러 발생!
str(msg)  # unicode를 str로 변환 시 ASCII 코덱 사용 → 실패

.format() 메서드도 마찬가지입니다.

# str + unicode 연산 시 ASCII 변환 시도 → 실패
"값: {}".format(msg)

---

해결 방법

1. 인코딩 명시하기

msg = u'안녕하세요'
msg.encode('utf-8')  # UTF-8로 명시적 인코딩

2. 포맷 문자열도 unicode로 만들기

u"값: {}".format(msg)  # 앞에 u를 붙여서 unicode끼리 연산

3. 파일 상단에 기본 인코딩 선언

# -*- coding: utf-8 -*-

4. Python 3으로 마이그레이션 (권장)

Python 3에서는 모든 문자열이 기본적으로 unicode이므로 이런 문제가 발생하지 않습니다.

---

마무리

Python 2.7의 문자열 처리 방식은 다소 복잡하고 혼란스러울 수 있습니다. 가능하다면 Python 3으로 업그레이드하는 것을 권장드리며, 당장 마이그레이션이 어렵다면 위의 해결 방법들을 활용해 보세요.

도움이 되셨다면 공감 부탁드립니다! 🙌