Write JSON to a file in Python

Save a dict as JSON, change it later, and never leave a half-written file behind.

To write JSON to a file in Python, open the file for writing and pass it to json.dump. Both come with the standard library.

The short answer

import json

data = {
    "site": {"name": "Nitro", "url": "https://nitro.sh"},
    "posts": [{"title": "Hello"}],
}

with open("site.json", "w", encoding="utf-8") as f:
    json.dump(data, f, indent=2)

Three choices in there are deliberate:

  • "w" creates the file, or replaces whatever was in it.
  • encoding="utf-8" is what every JSON reader expects. Without it, Windows picks a different default.
  • indent=2 makes the file readable and gives sensible diffs. Leave it out for the smallest file.

Add ensure_ascii=False if you want accented characters written as themselves rather than as \u escapes. json.dump does not end the file with a newline, so write one yourself if your editor or linter cares.

With pathlib

json.dumps builds the text and Path.write_text saves it:

from pathlib import Path

Path("site.json").write_text(json.dumps(data, indent=2), encoding="utf-8")

Do not leave a half-written file

Opening with "w" empties the file straight away. If json.dump then fails part of the way through, say on a value it cannot serialise, or the program is killed, you are left with a truncated file and the old contents are gone.

The usual protection is to write to a temporary file next to the real one and swap it in once it is complete:

import os


def write_json(path, data):
    tmp = f"{path}.tmp"
    with open(tmp, "w", encoding="utf-8") as f:
        json.dump(data, f, indent=2, ensure_ascii=False)
        f.write("\n")
    os.replace(tmp, path)


write_json("site.json", data)

os.replace is atomic when both paths are on the same filesystem, so a reader sees either the old file or the new one, never a mixture. The rest of this page uses write_json.

Update a JSON file

You cannot edit a JSON file in place. Read it, change the data in memory, and write the whole thing back:

with open("site.json", encoding="utf-8") as f:
    site = json.load(f)

site["site"]["name"] = "Nitro.sh"
site["site"]["theme"] = {"color": "#ffc700"}

write_json("site.json", site)

Avoid opening the file once in "r+" mode and writing over it. If the new text is shorter than the old, the tail of the old file is left behind and the result no longer parses.

Append to a JSON file

A JSON array ends with ], so there is nowhere to append to. Opening the file in "a" mode and dumping another object gives you two documents back to back, and the next json.load fails with Extra data.

Appending is the same read-modify-write, with list.append in the middle:

with open("site.json", encoding="utf-8") as f:
    site = json.load(f)

site["posts"].append({"title": "Second post"})

write_json("site.json", site)

That rewrites the whole file every time, which is fine for a config file or a few thousand records.

When you really need to append: JSON Lines

For logs and anything that grows without limit, use JSON Lines instead: one complete JSON value per line. Appending is then a real append, and nothing already in the file is touched.

with open("events.jsonl", "a", encoding="utf-8") as f:
    f.write(json.dumps({"event": "build", "ok": True}) + "\n")
    f.write(json.dumps({"event": "deploy", "ok": False}) + "\n")

with open("events.jsonl", encoding="utf-8") as f:
    events = [json.loads(line) for line in f if line.strip()]

len(events)          # 2
events[1]["event"]   # 'deploy'

Do not pass indent here. Each record has to stay on a single line.

The shorter way with Nitro DataStore

Nitro DataStore rolls the read-modify-write cycle into three calls:

from nitro_datastore import NitroDataStore

store = NitroDataStore.from_file("site.json")

store.set("site.theme.font", "Figtree")
store.posts.append({"title": "Third post"})

store.save("site.json")

set creates any missing levels on the way down, and save does what write_json does above: it writes to a temporary file, then replaces the original, with a two-space indent and non-ASCII characters left as they are. Use it when a program keeps editing the same nested file. To dump one dict once, json.dump is shorter than adding a dependency.

Common questions

What if two programs write the same file? The last one to save wins, and the other's changes are lost. Atomic replacement keeps the file valid but does not merge anything. If that can happen, use a lock file or move the data into SQLite.

Why does my file contain \u escapes? ensure_ascii is on by default. Pass ensure_ascii=False and keep encoding="utf-8" on the open call.

Should I use json.dump or json.dumps? dump writes to a file object. dumps returns a string, which is what you want for Path.write_text, a log line or an HTTP body. There is more in the json.dumps recipe.

How do I read the file back? With json.load, covered in reading a JSON file.

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