Developer Guide
JSON Parsing in Python
json.loads and load parse text; dumps and dump write it. JSONDecodeError carries line and column. Use parse_float=Decimal, default=str for datetime, and ensure_ascii=False for Unicode.
Python’s codec is the json module. json.loads parses a str (or UTF-8 bytes) into dicts, lists, str, int, float, True/False, and None. json.load does the same from a file object. The writers are dumps (to str) and dump (to a file). JSON true becomes Python True; forgetting that in a doctest is a rite of passage.
Invalid documents raise json.JSONDecodeError with lineno, colno, and pos. /tools/json-formatter is not a Python interpreter — it is a browser JSON.parse with line and column, format, minify, tree, and sort keys. Use it to inspect a payload before you argue with loads. This page does not cover JavaScript JSON.parse; that is a separate guide.
loads, load, dumps, dump
loads(s) is for strings you already have (an HTTP body, a Redis value). load(fp) reads a file object to EOF. Pair them with dumps(obj) and dump(obj, fp). Open text files with encoding='utf-8'.
json.dumps({'ok': True}) is '{"ok": true}'. json.dumps('hello') is '"hello"' — a JSON string, quotes included. indent=2 pretty-prints the way the formatter’s format mode does. separators=(',', ':') minifies. Skip a trailing comma; loads('{"a": 1,}') raises.
import json
json.loads('{"ok": true, "n": 1}')
# {'ok': True, 'n': 1}
with open('config.json', encoding='utf-8') as f:
data = json.load(f)
json.dumps({'ok': True}, indent=2)JSONDecodeError
JSONDecodeError is a ValueError subclass. Read e.msg, e.lineno, e.colno. For '{"a": 1,}' CPython reports Expecting property name enclosed in double quotes at line 1, column 9. Incomplete '{' fails at line 1, column 2.
Catch JSONDecodeError around input you do not control. Log the line and column; dump the raw text to /tools/json-formatter when the numbers are easier to see with a caret. Do not except Exception and retry with eval.
parse_float=Decimal
JSON numbers become int when they have no fraction, otherwise float. Binary floating point cannot represent 0.1 exactly. For money or measured decimals, pass parse_float=Decimal so json.loads('{"n": 0.1}', parse_float=Decimal) yields {'n': Decimal('0.1')}.
Decimal is not JSON-native on the way out: json.dumps({'n': Decimal('0.1')}) raises TypeError unless you provide default (often str or a function that emits float). Pick one representation and keep it stable.
from decimal import Decimal
json.loads('{"n": 0.1}', parse_float=Decimal)
# {'n': Decimal('0.1')}datetime with default=str
datetime is not a JSON type. json.dumps({'t': datetime(2026, 11, 13, tzinfo=timezone.utc)}) raises TypeError: Object of type datetime is not JSON serializable. default=str calls str() on unknown objects: {"t": "2026-11-13 00:00:00+00:00"}.
That string is Python’s datetime formatting, not necessarily ISO-8601 with T. If you need the JavaScript-shaped 2026-11-13T00:00:00+00:00, use .isoformat(). On parse, you get a str back unless you walk the dict yourself. There is no reviver argument like JavaScript’s.
from datetime import datetime, timezone
json.dumps(
{'t': datetime(2026, 11, 13, tzinfo=timezone.utc)},
default=str,
)
# '{"t": "2026-11-13 00:00:00+00:00"}'ensure_ascii
dumps defaults to ensure_ascii=True, so non-ASCII is escaped: json.dumps({'hi': 'नमस्ते'}) is {"hi": "\u0928\u092e\u0938\u094d\u0924\u0947"}. Both forms are valid JSON and loads to the same str. ensure_ascii=False keeps the Unicode characters: {"hi": "नमस्ते"}.
Use False for logs humans read and for files you edit. Keep True when a transport is 7-bit or a partner’s parser is old. /tools/json-formatter will accept either document.
Common pitfalls
Writing Python True/None into a file and calling it JSON. Using load on a path string — it wants a file object, so open first. Forgetting default for datetime and Decimal. Comparing dumps output across runs without sort_keys=True when key order is insertion order.
json will not encode sets, bytes, or circular lists. NaN/Infinity are allowed by default (allow_nan=True) and are not valid JSON; pass allow_nan=False to refuse them. Trailing commas still fail.
loads/dumpsfor strings;load/dumpfor files.JSONDecodeError.lineno/colnomatch what the formatter highlights.ensure_ascii=Falsewhen you want literal Unicode in the file.
Worked examples
Python True becomes JSON true
json.dumps({'ok': True}){"ok": true}json.loads of that string returns {'ok': True} — a Python bool, not the JSON token.
Trailing comma
json.loads('{"a": 1,}')JSONDecodeError: Expecting property name enclosed in double quotes (line 1 column 9)Paste {"a": 1,} into /tools/json-formatter to see the same class of error with a caret.
ensure_ascii on Devanagari
json.dumps({'hi': 'नमस्ते'}){"hi": "\u0928\u092e\u0938\u094d\u0924\u0947"}ensure_ascii=False yields {"hi": "नमस्ते"}. Both parse back to the same dict.
Frequently asked questions
What is the difference between load and loads?
loads parses a string (or bytes). load reads a file object. Same for dumps versus dump.
How do I serialize datetime?
default=str is the small hammer. Prefer .isoformat() if the other side is JavaScript. There is no built-in date type in JSON.
Why are my non-ASCII characters \u escaped?
ensure_ascii defaults to True. Set ensure_ascii=False to emit UTF-8 characters in the JSON text.
Does json.loads accept trailing commas?
No. You get JSONDecodeError with a line and column. The browser formatter rejects them too.
Can thedevtools.in execute my Python?
No. /tools/json-formatter parses JSON in the browser. Run json.loads on your own interpreter.
Summary
Use loads/dumps for strings and load/dump for files, catch JSONDecodeError, pass parse_float=Decimal when float is a lie, and give dumps a default for datetime. Pretty-print a failing document in /tools/json-formatter — the line and column should agree with CPython before you chase a network bug.