Python json Module Overview

The json module is Python’s built-in tool for working with JSON data.

Use it when you need to:

Read JSON text into Python
Convert Python data into JSON
Work with JSON files
Send or receive structured data in APIs

JSON is one of the most common data formats in programming, so learning the basic json functions is very useful.

Quick example #

import json

person = {"name": "Sam", "age": 25}
json_text = json.dumps(person)
print(json_text)

back_to_dict = json.loads(json_text)
print(back_to_dict["name"])

Output:

{"name": "Sam", "age": 25}
Sam

Use json.dumps() to convert a Python object to a JSON string, and json.loads() to convert a JSON string back to a Python object.

What the json module does #

The json module works with JSON data in Python.

A few key points:

JSON is a text format for storing and sending data
It is commonly used in APIs, configuration files, and data exchange
The json module is part of Python’s standard library
You do not need to install anything before using it

To use it, import it first:

import json

JSON vs Python data types #

When Python reads JSON, it converts JSON values into Python data types.

Here is the basic mapping:

JSON object → Python dictionary
JSON array → Python list
JSON string → Python string
JSON number → Python int or float
JSON true / false → Python True / False
JSON null → Python None

Example:

import json

json_text = '{"name": "Ana", "age": 30, "is_admin": false, "skills": ["Python", "SQL"], "manager": null}'
data = json.loads(json_text)

print(data)
print(type(data))
print(type(data["skills"]))
print(data["manager"])

Output:

{'name': 'Ana', 'age': 30, 'is_admin': False, 'skills': ['Python', 'SQL'], 'manager': None}
<class 'dict'>
<class 'list'>
None

If you want a refresher on dictionaries, see Python dictionaries explained.

Main functions to know #

These are the four json functions beginners see most often:

json.loads() reads JSON from a string
json.load() reads JSON from a file object
json.dumps() creates a JSON string from a Python object
json.dump() writes JSON to a file object

A simple way to remember them:

load = read
dump = write
extra s = string

If you want a deeper explanation of each one, see:

When to use each function #

Use the function based on what kind of data you already have.

Use `json.loads()` #

Use json.loads() when your JSON is already in a string.

import json

text = '{"city": "Paris", "country": "France"}'
data = json.loads(text)

print(data["city"])

Use `json.load()` #

Use json.load() when reading JSON from a file.

import json

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

print(data)

Use `json.dumps()` #

Use json.dumps() when you need JSON as a string.

import json

data = {"product": "Book", "price": 12.99}
text = json.dumps(data)

print(text)
print(type(text))

Use `json.dump()` #

Use json.dump() when saving Python data directly to a file.

import json

data = {"product": "Book", "price": 12.99}

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

If your goal is to parse JSON step by step, see how to parse JSON in Python.

Basic reading example #

Here is a simple example of reading JSON from a string.

import json

json_text = '{"name": "Lina", "age": 22, "active": true}'

data = json.loads(json_text)

print(data)
print(data["name"])
print(data["age"])
print(type(data))

Output:

{'name': 'Lina', 'age': 22, 'active': True}
Lina
22
<class 'dict'>

What happens here:

json_text is a string containing JSON
json.loads(json_text) converts that JSON into a Python dictionary
After that, you can access values with dictionary keys like data["name"]

Basic writing example #

Here is a simple example of converting a Python dictionary into JSON.

import json

person = {
    "name": "Lina",
    "age": 22,
    "active": True
}

json_text = json.dumps(person)

print(json_text)
print(type(json_text))

Output:

{"name": "Lina", "age": 22, "active": true}
<class 'str'>

Important:

json.dumps() returns a string
It does not return a dictionary

You can also pretty-print JSON using indent:

import json

person = {
    "name": "Lina",
    "age": 22,
    "active": True
}

json_text = json.dumps(person, indent=4)
print(json_text)

Output:

{
    "name": "Lina",
    "age": 22,
    "active": true
}

For more on formatting output, see how to pretty-print JSON in Python.

Working with JSON files #

JSON is often stored in files. In that case, use open() together with json.load() or json.dump().

Read JSON from a file #

Suppose data.json contains this:

{"username": "sam", "score": 100}

You can read it like this:

import json

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

print(data["username"])

Write JSON to a file #

import json

data = {"username": "sam", "score": 100}

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

Using with open(...) is the safest approach because Python closes the file automatically when you are done.

If you need to convert a dictionary before saving it, see how to convert a dictionary to JSON in Python.

Common beginner problems #

These are some of the most common mistakes when using the json module.

Mixing up `load` and `loads` #

This is a very common problem.

json.load(file) reads from a file object
json.loads(text) reads from a string

Wrong idea:

import json

text = '{"a": 1}'
data = json.load(text)  # wrong

Correct:

import json

text = '{"a": 1}'
data = json.loads(text)

Mixing up `dump` and `dumps` #

json.dump(data, file) writes to a file
json.dumps(data) returns a string

If you expect dumps() to create a file automatically, it will not. It only gives you a string.

Using single quotes in JSON text #

Python dictionaries can use single quotes, but JSON text must use double quotes.

Wrong JSON:

"{'name': 'Sam'}"

Valid JSON:

'{"name": "Sam"}'

Forgetting that JSON keys and strings use double quotes #

In JSON, object keys must use double quotes.

Invalid JSON:

'{name: "Sam"}'

Valid JSON:

'{"name": "Sam"}'

Trying to serialize unsupported Python objects directly #

Some Python objects cannot be converted to JSON automatically.

For example, a set will fail:

import json

data = {"numbers": {1, 2, 3}}
json_text = json.dumps(data)

This raises an error because sets are not standard JSON data types.

One simple fix is to convert the set to a list first:

import json

data = {"numbers": list({1, 2, 3})}
json_text = json.dumps(data)

print(json_text)

What this page does not cover in depth #

This page is an overview, so it does not go deep into every detail.

It does not fully cover:

Detailed behavior of each json function
Error handling for broken JSON
Advanced options such as custom encoders
Full API request workflows

If you are working with API responses, see how to handle API responses in Python.

Common causes of json problems #

If your code is not working, check for these common causes:

Using json.loads() on a file object instead of a string
Using json.load() on a plain string instead of a file object
Passing invalid JSON with single quotes
Trying to convert unsupported objects like sets without preprocessing
Assuming dumps() returns a dictionary instead of a string

Helpful commands for quick testing:

python --version
python -c "import json; print(json.dumps({'a': 1}))"
python -c "import json; print(type(json.loads('{\"a\": 1}')))"

If the JSON text is broken, you may also run into parsing errors. For general debugging help, see ValueError in Python: causes and fixes.

FAQ #

Is the json module built into Python? #

Yes. It is part of Python’s standard library, so you can use import json without installing anything.

What is the difference between `json.load()` and `json.loads()`? #

json.load() reads JSON from a file object. json.loads() reads JSON from a string.

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

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

Can JSON store every Python object? #

No. JSON supports basic data types like objects, arrays, strings, numbers, booleans, and null.

Why does my JSON text fail to load? #

A common reason is invalid JSON syntax, such as single quotes, missing commas, or missing double quotes around keys.

Python json Module Overview

Quick example #

What the json module does #

JSON vs Python data types #

Main functions to know #

When to use each function #

Use json.loads() #

Use json.load() #

Use json.dumps() #

Use json.dump() #

Basic reading example #

Basic writing example #

Working with JSON files #

Read JSON from a file #

Write JSON to a file #

Common beginner problems #

Mixing up load and loads #

Mixing up dump and dumps #

Using single quotes in JSON text #

Forgetting that JSON keys and strings use double quotes #

Trying to serialize unsupported Python objects directly #

What this page does not cover in depth #

Common causes of json problems #

FAQ #

Is the json module built into Python? #

What is the difference between json.load() and json.loads()? #

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

Can JSON store every Python object? #

Why does my JSON text fail to load? #

See also #

Use `json.loads()` #

Use `json.load()` #

Use `json.dumps()` #

Use `json.dump()` #

Mixing up `load` and `loads` #

Mixing up `dump` and `dumps` #

What is the difference between `json.load()` and `json.loads()`? #

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