json.dump() Function Explained

json.dump() writes Python data to a file in JSON format.

Use it when you want to save data like dictionaries or lists into a .json file. This is a common way to store settings, API data, or simple structured data.

Quick example

import json

data = {"name": "Alice", "age": 30}

with open("data.json", "w") as file:
    json.dump(data, file)

Use json.dump() when you want to write Python data directly to a file as JSON.

What json.dump() does

json.dump():

Writes Python data to a file in JSON format
Takes a Python object and a file object
Is commonly used with dictionaries and lists
Does not return the JSON string

This part is important:

json.dump() writes to a file
It does not give you the JSON text back as a return value

If you need the JSON text as a string instead, see json.dumps() explained.

Basic syntax

The basic syntax is:

json.dump(obj, file)

obj is the Python data you want to save
file must be an open file object in write mode
It is usually used inside a with open(...) block

Example:

import json

data = {"city": "Paris"}

with open("data.json", "w") as file:
    json.dump(data, file)

If you are not familiar with opening files, see open() explained and how to write to a file in Python.

Simple working example

Here is a complete example that writes a dictionary to a JSON file:

import json

person = {
    "name": "Alice",
    "age": 30,
    "is_admin": False
}

with open("data.json", "w") as file:
    json.dump(person, file)

What this code does

Opens data.json in write mode using "w"
Creates the file if it does not exist
Overwrites the file if it already exists
Writes the dictionary as JSON

Resulting file content

After running the code, data.json will contain:

{"name": "Alice", "age": 30, "is_admin": false}

Notice that JSON uses:

false instead of Python False
null instead of Python None

If you want a broader introduction, see the Python JSON module overview.

Common useful options

json.dump() has several optional arguments that are often useful.

Use `indent` to make JSON easier to read

Without indent, JSON is usually written on one line.

import json

data = {"name": "Alice", "age": 30, "skills": ["Python", "SQL"]}

with open("data.json", "w") as file:
    json.dump(data, file, indent=2)

Result in the file:

{
  "name": "Alice",
  "age": 30,
  "skills": [
    "Python",
    "SQL"
  ]
}

This is often called pretty-printed JSON. For more, see how to pretty-print JSON in Python.

Use `sort_keys=True` to sort dictionary keys

import json

data = {"b": 2, "a": 1, "c": 3}

with open("data.json", "w") as file:
    json.dump(data, file, indent=2, sort_keys=True)

This writes the keys in alphabetical order:

{
  "a": 1,
  "b": 2,
  "c": 3
}

Use `ensure_ascii=False` for non-English characters

By default, some non-English characters are escaped.

import json

data = {"name": "José", "city": "München"}

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

This keeps the characters readable in the file.

json.dump() vs json.dumps()

These two functions are similar, but they do different jobs.

`json.dump()`

Writes JSON directly to a file

import json

data = {"name": "Alice"}

with open("data.json", "w") as file:
    json.dump(data, file)

`json.dumps()`

Returns JSON as a string

import json

data = {"name": "Alice"}

json_text = json.dumps(data)
print(json_text)

Output:

{"name": "Alice"}

Use:

json.dump() for saving JSON to files
json.dumps() when you need the JSON text in memory

You can also see how to convert a dictionary to JSON in Python.

What data types work

json.dump() works with standard JSON-compatible Python types:

dict
list
str
int
float
bool
None

Nested combinations of these types also work.

Example:

import json

data = {
    "user": "Alice",
    "age": 30,
    "active": True,
    "scores": [10, 20, 30],
    "profile": {
        "country": "UK",
        "verified": False
    },
    "nickname": None
}

with open("data.json", "w") as file:
    json.dump(data, file, indent=2)

Types that do not work directly

Some Python types are not JSON serializable by default, such as:

set
Custom class objects

This example causes an error:

import json

data = {"numbers": {1, 2, 3}}

with open("data.json", "w") as file:
    json.dump(data, file)

Typical error:

TypeError: Object of type set is not JSON serializable

To fix this, convert the set to a list first:

import json

data = {"numbers": list({1, 2, 3})}

with open("data.json", "w") as file:
    json.dump(data, file)

For this specific problem, see TypeError: Object is not JSON serializable.

Common errors and fixes

Here are the most common problems beginners run into with json.dump().

1. Passing a file path instead of a file object

This is wrong:

import json

data = {"name": "Alice"}
json.dump(data, "data.json")

json.dump() expects an open file object, not a file name string.

Correct version:

import json

data = {"name": "Alice"}

with open("data.json", "w") as file:
    json.dump(data, file)

2. Using unsupported data types

This fails because set is not supported:

import json

data = {"items": {"apple", "banana"}}

with open("data.json", "w") as file:
    json.dump(data, file)

Fix it by converting the set:

import json

data = {"items": list({"apple", "banana"})}

with open("data.json", "w") as file:
    json.dump(data, file)

3. Confusing `json.dump()` with `json.dumps()`

If you want to save to a file, use json.dump().

If you want a string, use json.dumps().

4. Opening the file in the wrong mode

This is wrong:

import json

data = {"name": "Alice"}

with open("data.json", "r") as file:
    json.dump(data, file)

The file is opened in read mode, so Python cannot write to it.

Use write mode:

import json

data = {"name": "Alice"}

with open("data.json", "w") as file:
    json.dump(data, file)

5. Trying to save custom objects directly

This usually fails:

import json

class User:
    def __init__(self, name):
        self.name = name

user = User("Alice")

with open("data.json", "w") as file:
    json.dump(user, file)

Fix it by converting the object to a dictionary:

import json

class User:
    def __init__(self, name):
        self.name = name

user = User("Alice")
data = {"name": user.name}

with open("data.json", "w") as file:
    json.dump(data, file)

Helpful debugging checks

If json.dump() is failing, these checks can help:

print(type(data))
print(data)
print(json.dumps(data, indent=2))
print(file.mode)

These help you check:

What type your data is
What values it contains
Whether the data can be converted to JSON
Whether the file is open in the correct mode

FAQ

What is the difference between json.dump() and json.dumps()?

json.dump() writes JSON to a file. json.dumps() returns JSON as a string.

Does json.dump() create a file?

It writes to a file object. If you open a new file in write mode, Python creates it.

Can json.dump() write a list?

Yes. It can write lists, dictionaries, strings, numbers, booleans, and None.

Why does json.dump() give a TypeError?

Usually because the data contains a type that JSON cannot serialize, such as a set or custom object.