윈도우 콘솔 cp949 때문에 파이썬 print가 크래시할 때 force utf8로 해결한 실제 셋업

윈도우에서 Python 스크립트가 print() 한 줄 때문에 죽는다면, 대부분 콘솔 인코딩이 cp949인데 출력 문자열에 이모지, 특수기호, 일부 유니코드 문자가 섞였기 때문입니다. 가장 빠른 해결은 실행 환경에 PYTHONUTF8=1을 주거나 python -X utf8로 실행해 Python의 입출력 인코딩을 UTF-8로 강제하는 것입니다.

현재 터미널에서 PYTHONUTF8=1을 적용한 뒤 스크립트를 다시 실행해 보세요.

저는 Claude Code와 Cursor로 작은 자동화 스크립트를 만들다가 로그에 ✅, →, 파일 경로 설명을 찍는 순간 Windows PowerShell에서 UnicodeEncodeError: 'cp949' codec can't encode character가 나왔습니다. 코드는 맞는데 콘솔이 못 받아서 빌드가 멈춘 케이스라, 코드 수정 전에 실행 셋업부터 고치는 편이 훨씬 빨랐습니다.

결론: 한 번만 돌릴지, 계속 쓸지에 따라 설정 위치가 다릅니다

단발 실행이면 명령어 앞에 UTF-8 옵션을 붙이면 됩니다. 프로젝트에서 Claude Code, Codex CLI, Cursor 터미널이 계속 Python을 호출한다면 환경 변수로 고정하는 쪽이 안정적입니다.

단발 실행: python -X utf8

python -X utf8 script.py

이 방식은 현재 명령에만 적용됩니다. 원인을 확인하거나 CI와 로컬 차이를 빠르게 검증할 때 좋습니다.

현재 PowerShell 세션: PYTHONUTF8=1

$env:PYTHONUTF8="1"
python script.py

터미널을 닫으면 사라지는 임시 설정입니다. AI 코딩 에이전트가 열어준 터미널에서 바로 테스트하기 좋습니다.

코드 안에서 방어: stdout reconfigure

import sys
sys.stdout.reconfigure(encoding="utf-8")
print("✅ build complete")

배포 스크립트처럼 다른 사람이 다양한 터미널에서 실행할 가능성이 있으면 코드 레벨 방어도 유용합니다. 다만 모든 실행 환경에서 sys.stdout이 같은 객체라는 보장은 없으니, 기본값은 실행 환경에서 잡고 코드는 보조책으로 두는 편이 깔끔합니다.

왜 cp949에서 print가 터질까

Windows의 오래된 콘솔 환경은 한국어 코드 페이지인 cp949를 기본으로 쓰는 경우가 많습니다. 한글 대부분은 출력되지만 체크 이모지, 화살표, 일부 수학 기호, 다국어 문자는 cp949가 표현하지 못합니다.

문제가 되는 코드는 보통 복잡하지 않습니다.

print("✅ 파일 생성 완료 → output/result.json")

macOS, Linux, GitHub Actions에서는 멀쩡히 지나가는데 내 Windows 콘솔에서만 실패한다면 로직 문제가 아니라 출력 인코딩 문제일 가능성이 큽니다. 이때 chcp 65001만 입력하고 끝내면 해결되는 경우도 있지만, Python 런타임이 실제로 어떤 인코딩을 쓰는지는 별도로 확인해야 합니다.

해결 방식 비교: 무엇을 선택할까

빌더 워크플로 예시: AI 에이전트가 만든 로그 스크립트 고치기

가상의 예로, Cursor에서 Notion API 결과를 받아 Markdown 리포트를 만드는 report_builder.py를 만들었다고 해보겠습니다. 에이전트가 보기 좋게 로그를 넣으면서 ✅ fetched pages, → writing file 같은 문자를 출력합니다.

이 스크립트를 Windows PowerShell에서 실행하면 cp949 콘솔에서 실패할 수 있습니다. 저는 이런 작업이면 프로젝트 루트에 실행 파일을 하나 둡니다.

# run.ps1
$env:PYTHONUTF8="1"
python .\report_builder.py

이렇게 해두면 다음부터는 .\run.ps1만 실행하면 됩니다. Claude Code나 Codex에 “이 프로젝트는 Windows에서 run.ps1로 실행한다”고 알려주면, 에이전트가 매번 깨지는 명령을 다시 제안하는 일을 줄일 수 있습니다.

추천 대상: 어떤 설정이 가장 현실적인가

혼자 쓰는 로컬 자동화라면

PYTHONUTF8=1을 PowerShell 프로필이나 프로젝트 실행 스크립트에 넣는 것을 추천합니다. 매번 옵션을 기억하지 않아도 되고, 로그에 이모지나 특수문자가 들어가도 작업 흐름이 덜 끊깁니다.

팀이나 오픈소스에 배포한다면

문서에는 python -X utf8 또는 환경 변수 설정을 명시하고, 코드에서는 가능하면 로그 문자를 과하게 꾸미지 않는 편이 안전합니다. 특히 Windows 사용자가 많은 도구라면 README에 “Windows 콘솔에서 UnicodeEncodeError가 나면 UTF-8 모드로 실행” 문장을 넣어두면 이슈를 줄일 수 있습니다.

자주 막히는 지점

Q. 한글 출력도 안 되는 문제인가요?

항상 그렇지는 않습니다. cp949는 한국어를 상당 부분 지원하지만, 이모지나 일부 유니코드 기호를 못 담아서 실패하는 경우가 많습니다.

Q. Windows Terminal을 쓰면 자동으로 해결되나요?

Windows Terminal은 표시 환경이 좋아졌지만, Python 프로세스가 어떤 인코딩으로 stdout을 열었는지는 별개입니다. python -c "import sys; print(sys.stdout.encoding)"으로 확인해 보세요.

Q. 파일 저장 인코딩도 같이 바뀌나요?

UTF-8 모드는 기본 인코딩 동작에 영향을 줄 수 있지만, 파일을 열 때는 여전히 open(path, encoding="utf-8")처럼 명시하는 습관이 좋습니다. 출력 문제와 파일 읽기/쓰기 문제를 섞어 보면 디버깅이 길어집니다.

바로 할 다음 행동

먼저 현재 터미널에서 아래 두 줄을 실행해 보세요.

python -c "import sys; print(sys.stdout.encoding)"
python -X utf8 -c "print('✅ UTF-8 OK → 테스트')"

두 번째 명령이 통과하면 코드가 아니라 콘솔 인코딩 셋업 문제입니다. 그다음 프로젝트에 run.ps1을 만들고 PYTHONUTF8=1을 넣어두면, AI 코딩 에이전트가 만든 Python 스크립트를 Windows에서도 훨씬 덜 깨지게 돌릴 수 있습니다.

관련 링크

• .env 시크릿을 깃에 안 올리고 관리하기 gitignore 실수 복구까지, AI 코딩 프로젝트에서 바로 쓰는 셋업
• AutoWP 개발기 — OpenAI로 WordPress 콘텐츠 파이프라인을 만들고 사람이 검수하는 반자동 시스템
• PyInstaller onefile exe가 윈도우 디펜더에 오탐 차단될 때 뚫은 방법: 우회 말고 신뢰도부터 올렸다
• 관련 태그 더 보기
• 카테고리 더 보기
• 검색 결과 더 보기
• 참고 링크