JSON 파싱은 API 응답이나 설정 파일을 다루는 순간 매번 만나는데, 막히는 지점은 늘 비슷하다. json.loads에 뭘 넣어야 하는지, JSONDecodeError가 뜨면 어느 글자를 봐야 하는지, 한글이 \ud55c\uae00처럼 나오는 이유가 뭔지다. 이 글은 파이썬 표준 json 모듈만 써서 그 세 가지를 정리한다.
실제로 내 터미널에서 오류를 하나씩 재현하면서 메시지를 그대로 옮겨 적었다. 그래서 표에 있는 에러 문구는 외운 게 아니라 파이썬 3.9.6에서 찍힌 것이다.

30초 요약
| 항목 | 내용 |
|---|---|
| 문자열 파싱 | json.loads(s) — 결과는 dict·list 같은 파이썬 객체 |
| 파일 파싱 | json.load(f) — 텍스트 파일은 encoding="utf-8"을 직접 준다 |
| 실패 시 예외 | json.JSONDecodeError (내부적으로 ValueError의 하위 클래스) |
| 위치 확인 | e.msg, e.lineno, e.colno, e.pos 네 개만 보면 된다 |
| 한글 깨짐 | json.dumps(..., ensure_ascii=False) — 기본값이 True다 |
| 쓰기 실패 | TypeError: Object of type datetime is not JSON serializable → default= |
| 표준 | JSON은 RFC 8259와 ECMA-404로 정의된다 (파이썬 문서) |
목차
- JSON 파싱이 뭐고 어디에 쓰나
- 파이썬 JSON 파싱 방법 4가지
- 문자열 파싱 — json.loads 기본
- 파일 파싱 — json.load와 인코딩
- JSONDecodeError 메시지별 원인과 해결
- 한글이 깨질 때 — ensure_ascii
- 객체를 JSON으로 쓸 때 나는 TypeError
- 내가 막혔던 곳
JSON 파싱이 뭐고 어디에 쓰나
파싱(parsing)은 문자열을 프로그램이 다룰 수 있는 구조로 바꾸는 일이다. JSON 문자열 {"id": 1}을 파이썬에서 json.loads에 넣으면 {'id': 1}이라는 dict가 나온다. 그 뒤로는 data["id"]처럼 평범한 딕셔너리 문법으로 값을 꺼낸다.
내가 JSON을 가장 많이 만지는 자리는 세 곳이다. REST API 응답, package.json이나 tsconfig.json 같은 설정 파일, 로그를 JSON 한 줄씩 남긴 파일(ndjson). 셋 다 "텍스트를 읽어서 구조로 바꾼다"는 점은 같고, 입력이 문자열이냐 파일이냐만 다르다.
파이썬 JSON 파싱 방법 4가지
| 하고 싶은 일 | 함수 | 입력 | 결과 |
|---|---|---|---|
| 문자열 → 객체 | json.loads(s) | str, bytes, bytearray | dict·list 등 |
| 파일 → 객체 | json.load(f) | .read()가 되는 파일 객체 | dict·list 등 |
| 객체 → 문자열 | json.dumps(obj) | dict·list 등 | str |
| 객체 → 파일 | json.dump(obj, f) | + .write() 파일 객체 | 파일에 기록 |
함수 이름이 헷갈리면 s가 붙은 쪽은 string, 안 붙은 쪽은 stream(파일) 이라고 외우면 된다. 이 구분은 pickle.load/pickle.loads와도 같다.
문자열 파싱 — json.loads 기본
import json
raw = '{"id": 1, "tags": ["json", "python"], "ok": true}'
data = json.loads(raw)
print(data["id"]) # 1
print(data["tags"][0]) # json
print(type(data["ok"])) # <class 'bool'>
JSON의 true/false/null은 파이썬에서 True/False/None으로 바뀐다. 이 변환표는 공식 문서의 디코딩 표에 그대로 있다.
json.loads는 파이썬 3.6부터 bytes도 받는다. 다만 입력 인코딩이 UTF-8·UTF-16·UTF-32 중 하나여야 하고, 아니면 UnicodeDecodeError가 난다. 인코딩 문제로 막혔을 때는 UnicodeDecodeError 해결 글에 케이스별로 정리해 뒀다.
파일 파싱 — json.load와 인코딩
import json
# 텍스트 모드: open()의 기본 인코딩은 OS 설정을 따른다
with open("config.json", encoding="utf-8") as f:
config = json.load(f)
# 이진 모드: json.load가 UTF-8/16/32를 스스로 판별한다
with open("config.json", "rb") as f:
config = json.load(f)
여기서 한 번 크게 데었다. open("config.json")만 쓰면 맥에서는 잘 되고 윈도우나 도커 컨테이너에서는 한글 값이 깨지거나 UnicodeDecodeError가 났다. 파이썬 open()의 기본 인코딩이 플랫폼 로캘을 따르기 때문이다. encoding="utf-8"을 항상 붙이는 습관을 들이고 나서 이 문제는 사라졌다.
BOM이 붙은 파일은 encoding="utf-8-sig"로 열어야 한다. UTF-8 BOM은 JSON 스펙에 없는 문자라, 그냥 utf-8로 읽으면 json.loads가 Unexpected UTF-8 BOM (decode using utf-8-sig)이라고 알려 준다.
JSONDecodeError 메시지별 원인과 해결
json.JSONDecodeError는 ValueError의 하위 클래스라서 except ValueError로도 잡힌다. 다만 원인을 알려면 메시지를 읽어야 한다. 아래는 내가 직접 재현한 결과다.
| 입력 | 메시지 | 실제 원인 |
|---|---|---|
{'a': 1} | Expecting property name enclosed in double quotes | 작은따옴표. JSON은 큰따옴표만 허용한다 |
{"a": 1,} | Expecting property name enclosed in double quotes (line 1 column 9) | 마지막 쉼표(trailing comma) |
{"a": 1 // hi} | Expecting ',' delimiter | 주석. JSON에는 주석 문법이 없다 |
{"a": 1} {"b": 2} | Extra data (char 8) | 객체 두 개를 이어 붙임(ndjson) |
"" (빈 문자열) | Expecting value (line 1 column 1) | 응답이 비었다. 대개 에러 응답을 안 봤을 때 |
{a: 1} | Expecting property name enclosed in double quotes | 키에 따옴표를 안 붙임 |
메시지가 알려 주는 위치를 코드로 뽑으면 이렇게 된다.
import json
try:
json.loads('{"a": 1,}')
except json.JSONDecodeError as e:
print(e.msg) # Expecting property name enclosed in double quotes
print(e.lineno) # 1
print(e.colno) # 9
print(e.pos) # 7 ← 문자열에서의 인덱스
pos는 0부터 세는 인덱스고 colno는 1부터 센다. 그래서 같은 자리를 가리키는데 숫자가 하나 다르다. 이 차이를 모르고 s[e.pos]를 찍었다가 엉뚱한 글자를 보고 한참 헤맨 적이 있다. 사람에게 보여 줄 때는 lineno/colno를, 문자열을 잘라 볼 때는 pos를 쓰면 된다.
"Extra data"는 특히 API에서 자주 나온다. 스트리밍 응답이나 로그 파일처럼 JSON 객체가 여러 개 이어질 때 json.loads는 첫 객체를 읽고 남은 글자에서 실패한다. 한 줄씩 처리하려면 splitlines() 후 각 줄을 파싱하고, 한 문자열에서 연속으로 읽으려면 json.JSONDecoder().raw_decode(s)를 반복 호출한다. raw_decode는 (객체, 끝난 위치) 튜플을 돌려준다.
한글이 깨질 때 — ensure_ascii
import json
print(json.dumps("한글")) # "\ud55c\uae00"
print(json.dumps("한글", ensure_ascii=False)) # "한글"
ensure_ascii의 기본값이 True라서, 따옴표를 뺀 본문 2글자가 12글자 이스케이프로 늘어난다. 파일에 한글을 그대로 저장하고 싶으면 ensure_ascii=False를 주고 파일을 UTF-8로 열면 된다. 이스케이프된 값도 json.loads로 읽으면 원래 한글로 돌아오니 데이터가 깨진 건 아니다. 사람이 읽기 불편한 것뿐이다.
읽을 때 깨지는 경우는 대부분 인코딩 쪽 문제다. 파일은 UTF-8인데 윈도우 기본값(cp949)으로 열었거나, 반대로 cp949 파일을 UTF-8로 강제로 읽은 경우다. 앞 절의 encoding="utf-8"과 utf-8-sig를 먼저 확인하자.
객체를 JSON으로 쓸 때 나는 TypeError
import json, datetime
json.dumps(datetime.datetime.now())
# TypeError: Object of type datetime is not JSON serializable
set, bytes도 같은 메시지가 난다. JSON 스펙에 그 타입이 없기 때문이다. 해결은 두 가지다. 값을 미리 문자열로 바꾸거나, default=에 변환 함수를 준다.
def to_jsonable(o):
if isinstance(o, datetime.datetime):
return o.isoformat()
raise TypeError(f"직렬화할 수 없는 타입: {type(o)}")
print(json.dumps({"at": datetime.datetime(2026, 11, 21, 9, 0)}, default=to_jsonable))
# {"at": "2026-11-21T09:00:00"}
파일에 쓸 때 open(path, "wb")로 열면 TypeError: a bytes-like object is required, not 'str'이 난다. json 모듈은 항상 str을 만들기 때문에 파일도 텍스트 모드("w", encoding="utf-8")로 열어야 한다. 이건 공식 문서의 dump() 설명에 "fp.write() must support str input"이라고 적혀 있다.
같은 파일에 json.dump를 여러 번 호출하면 유효한 JSON이 되지 않는다. JSON은 pickle처럼 프레임이 있는 형식이 아니라서, 문서에도 "repeated calls to dump() using the same fp will result in an invalid JSON file"이라고 나온다. 여러 건을 남기려면 리스트로 모아 한 번에 쓰거나, 한 줄에 한 객체씩(ndjson) 직접 쓰는 편이 낫다.
숫자 하나만 주의할 점도 있다. allow_nan 기본값이 True라서 NaN과 Infinity가 그대로 출력된다. 이건 JSON 표준 밖이라 자바스크립트 JSON.parse가 거부한다. 다른 언어와 주고받는 API라면 allow_nan=False로 두고 ValueError를 미리 만나는 게 낫다.

내가 막혔던 곳
처음에 API 응답을 json.loads(response.text)로만 처리했다. 200이 아닐 때도 그대로 파싱을 시도해서 Expecting value: line 1 column 1 (char 0)만 반복해서 봤다. 원인은 JSON이 아니라 HTML 에러 페이지였는데, 메시지만 보면 JSON 문법 문제처럼 보인다. 지금은 파싱 전에 상태 코드를 먼저 확인하고, 실패하면 본문 앞 200자만 로그로 남긴다. 이 습관 하나로 디버깅 시간이 확 줄었다. 오픈AI API 응답을 다룰 때도 같은 순서를 쓴다(OpenAI API 사용법).
두 번째는 판다스 데이터를 그대로 json.dumps에 넣은 일이다. numpy.int64가 Object of type int64 is not JSON serializable로 걸렸다. int()로 감싸거나 df.to_dict() 후 default=str을 주면 통과한다. 타입 이름이 메시지에 그대로 나오니, 에러를 읽는 습관만 들이면 대부분 5분 안에 끝난다.
참고 자료
- Python 공식 문서 — json: JSON encoder and decoder
- RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format
- ECMA-404 — The JSON Data Interchange Syntax
- JSON.org
관련 글: OpenAI API 사용법 (Python) · Claude API 사용법 (Python) · UnicodeDecodeError 해결
'IT' 카테고리의 다른 글
| OpenAI API 사용법 — 파이썬 첫 호출부터 요금·에러까지 (0) | 2026.11.20 |
|---|---|
| 어사이드 vs 에고 라이트 vs 핸들러스 — 내 브라우저를 AI에게 맡기는 3가지 방법 (0) | 2026.11.20 |
| 에고 라이트(ego lite) 사용법 — 클로드코드가 내 로그인 브라우저를 쓴다 (0) | 2026.11.20 |
| 핸들러스(Handlus) MCP 사용법 — 클로드코드가 내 브라우저를 직접 조작한다 (0) | 2026.11.20 |
| Claude MCP 설정 방법 — claude mcp add로 서버 붙이고 /mcp로 확인하기 (0) | 2026.11.19 |


















