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:

  • with closes 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.

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