# JSON Files: Saving Your Data

JSON is a text format for data that json.dump and json.load turn Python's dictionaries and lists into and back from, through a file, while json.dumps and json.loads do the same with a string, which is how web APIs send their answers.

Apprentice · Python · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Save Python data to a JSON file with json.dump and load it back with json.load
- Turn data into JSON text and back with json.dumps and json.loads, and say which Python values JSON can hold

## Key takeaways

- JSON is a text format for data, with objects in curly braces, lists in square brackets, text in double quotes, numbers, true, false and null.
- json.dump(data, file) writes Python data to an open file as JSON, and json.load(file) reads it back as the same dictionaries and lists.
- json.dumps() turns data into a JSON string and json.loads() turns a JSON string into data, which is how a web API's answer is read.
- indent=2 spreads the JSON over several lines, two spaces deeper for each level, so a person can read it.
- A tuple comes back from JSON as a list and a number key as text, and a set can't be saved at all.

A program's data is rarely a few lines of text. It's a dictionary of settings, a list of contacts, a game's saved state: data with a shape. To keep it between runs, or send it to another program, you need a way to write that shape down and read it back exactly. JSON is that way, and it's everywhere: settings files, saved data, and almost every answer a web API sends.

The example is the Riverbend Running Club's goals: how many miles each member plans to run in a week.

## Saving a dictionary as text

The goals are a dictionary. Writing it to a text file with `str()` looks like it works:

```python
goals = {"Priya": 15, "Marcus": 20}

with open("goals.txt", "w", encoding="utf-8") as file:
    file.write(str(goals))

with open("goals.txt", encoding="utf-8") as file:
    loaded = file.read()

print(loaded)
print(type(loaded))
```

```text
{'Priya': 15, 'Marcus': 20}
<class 'str'>
```

`open()` with `"w"` writes the file and with no mode reads it, and the `with` block closes the file when its lines are done. What comes back looks like the dictionary, but `type()` says it's a string: `loaded["Priya"]` stops with a `TypeError`, because a string's characters are found by number. Turning the text back into a dictionary would mean taking it apart character by character.

## What JSON looks like

**JSON** (read "jay-son", short for JavaScript Object Notation) is a way of writing data as text that programs in every language can read back. The club's goals, with each member's races, look like this in JSON:

```json
{
  "Priya": {"weekly_miles": 15, "races": ["Riverbend 5K"]},
  "Marcus": {"weekly_miles": 20, "races": []}
}
```

It looks a lot like Python, with a few differences in spelling:

| Python | JSON |
|---|---|
| `dict`, `{"Priya": 15}` | object, `{"Priya": 15}` |
| `list`, `["Riverbend 5K"]` | array, `["Riverbend 5K"]` |
| `str`, `"Priya"` or `'Priya'` | string, `"Priya"` (double quotes only) |
| `int` and `float`, `15`, `4.5` | number, `15`, `4.5` |
| `True`, `False` | `true`, `false` |
| `None` | `null` |

## Saving and loading with json.dump and json.load

Python's built-in **`json` module** writes and reads JSON for you. `import json` brings it in:

```python
import json

goals = {
    "Priya": {"weekly_miles": 15, "races": ["Riverbend 5K"]},
    "Marcus": {"weekly_miles": 20, "races": []},
}

with open("goals.json", "w", encoding="utf-8") as file:
    json.dump(goals, file, indent=2)

with open("goals.json", encoding="utf-8") as file:
    loaded = json.load(file)

print(loaded["Priya"]["races"][0])
print(loaded == goals)
```

```text
Riverbend 5K
True
```

`json.dump(goals, file)` writes the dictionary into the open file as JSON, and `json.load(file)` reads it back as a real dictionary, lists inside it and all, equal to the one that was saved. `indent=2` lays the file out over several lines, each level two spaces deeper than the one around it, so `goals.json` reads like this:

```json
{
  "Priya": {
    "weekly_miles": 15,
    "races": [
      "Riverbend 5K"
    ]
  },
  "Marcus": {
    "weekly_miles": 20,
    "races": []
  }
}
```

Without `indent`, the whole file is one long line: fine for a program, hard for a person.

## JSON as a string: dumps and loads

Sometimes the JSON isn't in a file: a web API sends its answer as JSON text, and a program may want JSON text to print or send. `json.dumps()` and `json.loads()` do the same jobs with a string (the `s` is for string):

```python
import json

goals = {"Priya": 15, "Marcus": 20}
print(json.dumps(goals))

answer = '{"runner": "Luis", "miles": 2.6, "finished": true, "medal": null}'
run = json.loads(answer)
print(run["miles"] + 1)
print(run["finished"], run["medal"])
```

```text
{"Priya": 15, "Marcus": 20}
3.6
True None
```

`json.loads()` turned the text into a dictionary, so `run["miles"]` is a number you can add to, and JSON's `true` and `null` came back as Python's `True` and `None`.

JSON holds only what the table shows, so some values change shape on the way through. A tuple is saved as an array and comes back as a list. A dictionary's keys are always strings in JSON, so a key of `1` comes back as `"1"`. A set has no JSON spelling at all: `json.dumps({"Riverbend 5K"})` stops with `TypeError: Object of type set is not JSON serializable`. Turn it into a list first, with `list()`.

## Do it: update one member's goal

The club keeps every member's weekly goal in a JSON file: an object with each member's name and their goal in miles, such as `{"Priya": 15, "Marcus": 20}`. A member changes their goal, and the file has to be changed to match.

- `path`: the JSON file's name. The file is already there.
- `runner`: the member's name.
- `miles`: their new weekly goal.

**Your job:** write the function `set_goal(path, runner, miles)` so it loads the goals from the file at `path`, sets `runner`'s goal to `miles`, saves all the goals back to the same file, and returns the updated dictionary.

- Load with `json.load` and save with `json.dump`, opening the file with `encoding="utf-8"` each time.
- A member who's already in the file gets their new goal; everyone else keeps theirs.
- A member who isn't in the file yet is added.

Worked through: the file holds `{"Priya": 15, "Marcus": 20}`. `set_goal("goals.json", "Marcus", 25)` loads that dictionary, changes Marcus's goal to 25, saves it, and returns `{"Priya": 15, "Marcus": 25}`, which is now what the file holds too.

Practiced live on the lesson page: write the Python right there and check it.

## Check yourself

2 questions to try on the lesson page.

## So what

JSON is how programs save their data and how they talk to each other, so `json.dump`, `json.load`, `dumps` and `loads` are the four lines that connect your program to files, settings and web APIs alike.

## Key terms

- [JSON](https://www.ask-codey.com/glossary/json)
- [json Module](https://www.ask-codey.com/glossary/json-module)

## Related

- [Reading and Writing Text Files](https://www.ask-codey.com/lessons/python-files-reading-and-writing)
- [CSV Files: Tables in Plain Text](https://www.ask-codey.com/lessons/python-files-csv)

Source: https://www.ask-codey.com/lessons/python-files-json
