Read a JSON file in Python
Open a JSON file, get a dict back, and handle the three ways it goes wrong.
Python reads JSON with the json module from the standard library. There is nothing to install.
The short answer
import json
with open("config.json", encoding="utf-8") as f:
config = json.load(f)
print(config["site"]["name"]) # Nitro
json.load takes an open file and returns ordinary Python objects. A JSON object becomes a dict, an array becomes a list, and true, false and null become True, False and None.
Two details in those three lines are easy to skip and worth keeping:
withcloses the file for you, even if parsing fails halfway.encoding="utf-8"matters on Windows, where the default encoding is not UTF-8 and a file with an accented character or an emoji will fail to read.
load or loads?
json.load reads from a file. json.loads (with an s, for "string") reads from text you already have in memory:
text = '{"name": "Nitro", "stars": 120}'
data = json.loads(text)
Passing a filename to json.loads is the most common mistake here. It tries to parse the filename itself as JSON and raises a JSONDecodeError about an unexpected character on line 1.
Read a JSON file into a dictionary
If the top level of the file is an object, json.load already gives you a dict. If it is an array, you get a list. When you need to be sure, check:
with open("config.json", encoding="utf-8") as f:
config = json.load(f)
if not isinstance(config, dict):
raise TypeError("config.json should contain an object at the top level")
With pathlib
If you are already working with Path objects, you can skip open altogether:
from pathlib import Path
config = json.loads(Path("config.json").read_text(encoding="utf-8"))
When the file is missing or broken
Three things go wrong in practice: the file is not there, it is not valid JSON, or it is valid but does not have the key you expected.
def read_json(path):
try:
with open(path, encoding="utf-8") as f:
return json.load(f)
except FileNotFoundError:
print(f"{path} does not exist")
except json.JSONDecodeError as e:
print(f"{path} is not valid JSON: line {e.lineno}, column {e.colno}")
return None
read_json("missing.json") # missing.json does not exist
read_json("broken.json") # broken.json is not valid JSON: line 1, column 27
JSONDecodeError tells you the line and column where parsing stopped, which is usually one character after the real mistake. A trailing comma, as in broken.json here, is the usual cause: JSON does not allow them, even though Python does.
Reading nested values safely
Indexing straight into nested data works until a key is missing:
config["site"]["name"] # 'Nitro'
try:
config["site"]["theme"]["color"]
except KeyError as e:
print(f"missing key: {e}") # missing key: 'theme'
The standard fix is a chain of .get() calls with empty-dict fallbacks:
color = config.get("site", {}).get("theme", {}).get("color", "#000")
That works, and it gets harder to read with every level.
The shorter way with Nitro DataStore
Nitro DataStore wraps a JSON file so you can use a dotted path with a default, or plain attribute access:
from nitro_datastore import NitroDataStore
config = NitroDataStore.from_file("config.json")
config.site.name # 'Nitro'
config.get("site.theme.color", "#000") # '#000', no KeyError
config.has("site.url") # True
It is still a plain dict underneath, and config.to_dict() hands it back whenever you need one. Reach for it when you read the same nested file in many places; for a one-off script, json.load is all you need.
Common questions
Does json.load keep the order of keys? Yes. Dicts keep insertion order, so keys come back in the order they appear in the file.
Can it read a file with comments? No. Standard JSON has no comments, and json.load rejects them. If you control the file, move the comments out or switch to YAML or TOML.
What about a very large file? json.load reads the whole file into memory. For files in the hundreds of megabytes, look at a streaming parser such as ijson, or store one JSON object per line and read it line by line.
Related
Parse JSON in Python
Turn JSON text into dicts and lists, and deal with text that is not JSON after all.
Read ->Write JSON to a file in Python
Save a dict as JSON, change it later, and never leave a half-written file behind.
Read ->Pretty print JSON in Python
Indent it, sort it, and format a file without writing a script.
Read ->This page uses Nitro DataStore.
Read JSON with dot notation and a chainable query builder. No schema to define, no ORM to learn.
$ pip install nitro-datastore