한 줄 결론. Windows PowerShell의
Out-File -Encoding utf8은 한국어를 더블 UTF-8로 인코딩해 백업 파일을 깨뜨립니다.
한글 텍스트 파일 저장은 PowerShell 대신 Python json.dump(..., ensure_ascii=False)로 우회하세요.
문제 상황
내가 시도한 작업은 단순했습니다. 외부 API에서 한국어 본문을 받아 백업용 JSON 파일로 디스크에 저장하는 것이었습니다. 자동화 스크립트의 일부였고, PowerShell의 표준 명령인 Out-File -Encoding utf8을 그대로 사용했습니다.
에러 증상
저장된 JSON 파일을 다시 Python json.load로 읽었을 때 한글이 전혀 다른 문자로 출력됐습니다.
- 원본 한국어 단어:
안녕하세요 테스트 - JSON 파일 안의 같은 위치:
안녕하세요 테스트
한국어 키워드로 grep하면 0건. 영어와 코드 토큰은 정상이라 파일 인코딩 자체는 살아있었습니다. 운영 기록 기준 같은 PowerShell 환경에서 100% 재현됐습니다.
환경
- Windows 11 Pro
- Windows PowerShell 5.1 (기본 내장)
- Python 3.12 / requests 2.31
시도했지만 실패한 방법
- Out-File에
-Encoding utf8명시 — 결과 동일. BOM이 박히고 한글 바이트는 그대로 더블 인코딩. - Python load 시
encoding="utf-8-sig"사용 — BOM은 제거되지만 본문 한글은 여전히 깨진 문자로 남음. 인코딩 처리 위치를 옮긴 것뿐이라 의미 없음. - UTF-16으로 우회 저장 — 다른 도구가 못 읽음. 호환성 X.
원인
정확한 동작은 PowerShell 5.1의 내부 처리에서 발생합니다.
- 한국어 글자 한 개는 정상 UTF-8 3 bytes
- PowerShell이 이 3 bytes를 latin-1 (single-byte) 문자열로 재해석
- 재해석된 결과를 다시 UTF-8로 인코딩 → 6 bytes의 mojibake
결과적으로 파일은 정상 UTF-8 인코딩이지만 안의 한글은 깨진 문자열입니다. PowerShell 7.0+ 부터는 기본이 UTF-8로 바뀌어 이 문제가 사라졌지만, Windows 11 기본 PowerShell 5.1을 쓰는 환경에서는 여전히 재현됩니다.
최종 해결
PowerShell을 우회하고 Python으로 직접 저장하는 방식으로 전환했습니다.
# 한국어 JSON 백업 — Python only
import requests, json
r = requests.get(api_url)
data = r.json()
with open(out_path, "w", encoding="utf-8") as f:
json.dump(data, f, ensure_ascii=False)
핵심은 ensure_ascii=False. 이 옵션이 없으면 JSON에 한글이 \uXXXX 이스케이프로 박혀 가독성이 떨어집니다. 내부 작업용 백업은 그래도 정상 동작하지만, 사람이 열어볼 백업이면 False가 낫습니다.
검증 결과
위 코드로 백업한 JSON을 다시 Python json.load로 읽어 한국어 키워드를 grep한 결과:
- 한국어 키워드 (예:
안녕하세요,테스트,저장) 모두 정상 매칭 - 본문 길이 / hangul count 둘 다 원본과 일치
- JSONDecodeError 0건 (BOM 문제도 사라짐)
현재 상태
fixed. 자동화 스크립트에서 PowerShell Out-File을 한글 텍스트 저장 용도로 사용하는 부분은 모두 Python 직접 저장으로 교체했습니다. 운영 기록 기준 같은 mojibake 재발 0건.
같은 문제 겪는 분들에게
- 먼저 PowerShell 버전 확인:
$PSVersionTable.PSVersion. Major가 5라면 이 문제가 발생합니다. - 처리 위치를 바꾸지 말 것: PowerShell 저장은 그대로 두고 Python read만
utf-8-sig로 바꾸면 BOM만 해결되고 본문 mojibake는 그대로 남습니다. - 가장 빠른 우회: 한글 텍스트는 PowerShell을 거치지 말고 Python으로 직접 저장하세요.
- PowerShell이 꼭 필요하다면: PowerShell 7+ 로 업그레이드. 그래도 일관성을 위해 핵심 텍스트 처리는 Python 단일 경로 권장입니다.