← Guides

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.

json.loads pythonjson.dumps ensure_asciijsondecodeerror lineno colnoparse_float decimaljson dumps default str

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/dumps for strings; load/dump for files.
  • JSONDecodeError.lineno / colno match what the formatter highlights.
  • ensure_ascii=False when you want literal Unicode in the file.

Worked examples

Python True becomes JSON true

Input
json.dumps({'ok': True})
Output
{"ok": true}

json.loads of that string returns {'ok': True} — a Python bool, not the JSON token.

Trailing comma

Input
json.loads('{"a": 1,}')
Output
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

Input
json.dumps({'hi': 'नमस्ते'})
Output
{"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.

Try it yourself

Put what you've learned into practice with our free browser-native tool.

Open Tool →