How to Write JSON Data to a File in Python

By the end of this page, you will understand why a Python dictionary cannot be written directly to a file as JSON, how to convert Python data into JSON text, and how to save it correctly using json.dump() and json.dumps(). You will also learn common mistakes, real-world usage patterns, and how this works in real Python projects.

A Python dict and JSON are closely related, but they are not the same thing.

• A Python dictionary is an in-memory Python object.
• JSON is a text format used to store and exchange structured data.

When you call:

f.write(data)

Python expects data to already be a string or bytes object. But data is a dictionary, so Python raises this error:

TypeError: must be string or buffer, not dict

To write JSON to a file, you must first serialize the dictionary. Serialization means converting a Python object into a format that can be stored or transmitted. In this case, the format is JSON text.

Python provides the built-in json module for this:

• json.dump(obj, file) writes JSON directly to a file.
• json.dumps(obj) returns a JSON string.

This matters in real programming because JSON is everywhere:

• API responses
• configuration files
• logging structured data
• saving application state
• exporting data

If you understand the difference between Python objects and JSON text, file writing becomes much easier and less error-prone.

Think of a Python dictionary as a set of labeled containers in your program's memory.

data = {"name": "Ava", "age": 25}

That structure works well inside Python, but a file cannot store a live Python object directly. A file stores text or bytes.

JSON is like a written version of that dictionary that other programs can read:

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

So the process is:

1. Start with a Python object.
2. Convert it into JSON text.
3. Write that text into a file.

A simple way to remember it:

• dict = Python data structure
• JSON = text representation of that structure
• file = place where the text is stored

The most common and correct way to write a Python dictionary to a JSON file is with json.dump().

import json

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

with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(data, f)

What this does

• import json loads Python's JSON module.
• open(..., 'w') opens the file for writing as text.
• json.dump(data, f) converts the dictionary to JSON and writes it to the file.

Writing pretty-formatted JSON

import json

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

with open('data.json', 'w', encoding='utf-8')  f:
    json.dump(data, f, indent=)

Consider this example:

import json

data = {
    "user": "sam",
    "active": True
}

with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(data, f)

Step-by-step

1. import json

   • Python loads the JSON module.

2. data = {...}

   • A dictionary is created in memory.
   • At this point, it is still a Python object, not JSON text.

3. open('data.json', 'w', encoding='utf-8')

   • Python opens data.json in text write mode.
   • If the file does not exist, it is created.
   • If it already exists, its contents are replaced.

4. with ... as f:

   • The file object is assigned to f.
   • When the block finishes, Python automatically closes the file.

Writing JSON files is common in many Python programs.

Saving configuration

Applications often store settings in JSON files:

config = {
    "theme": "dark",
    "autosave": True,
    "font_size": 14
}

Exporting API data

If your script fetches data from an API, you may save the response for later:

import json

response_data = {
    "status": "ok",
    "results": [1, 2, 3]
}

with open('response.json', 'w', encoding='utf-8') as f:
    json.dump(response_data, f, indent=2)

Logging structured results

Data-processing scripts often store summaries in JSON:

• number of records processed
• failed items
• timestamps
• performance metrics

Caching data

Programs sometimes save processed results to JSON so they do not need to recompute them every time.

Storing simple app state

Small tools and command-line apps often save user preferences or session state as JSON files because JSON is easy to read and edit.

In real projects, developers usually do more than just call json.dump().

Common pattern: use with open(...)

This ensures files are closed properly, even if an error occurs.

with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(data, f)

Common pattern: pretty-print for humans

When the file may be read by developers or users, indent is often used.

json.dump(data, f, indent=2)

Common pattern: preserve non-ASCII characters

json.dump(data, f, ensure_ascii=False, indent=2)

This is useful for names, languages, and international text.

Common pattern: validation before writing

Developers often check that required fields exist before saving.

def save_user(user):
    if "id"   user:
         ValueError()

     (, , encoding=)  f:
        json.dump(user, f, indent=)

Mistake 1: Writing a dictionary directly

Broken code:

data = {"a": 1}

with open('data.json', 'w', encoding='utf-8') as f:
    f.write(data)

Why it fails:

• f.write() expects a string.
• data is a dictionary.

Fix:

import json

with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(data, f)

Mistake 2: Opening the file in binary mode unnecessarily

Broken code:

with open('data.json', 'wb') as f:
    json.dump(data, f)

Why it is a problem:

• JSON is typically written as text, not binary.
• Use 'w' instead of unless you have a very specific reason.

str(data) vs JSON

import json

Write a dictionary to JSON file

with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(data, f)

Write pretty JSON

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

Get JSON as a string

json_text = json.dumps(data)

Write a JSON string manually

with open('data.json', 'w', encoding='utf-8') as f:
    f.write(json.dumps(data))

Key rules

• dict is not JSON text
• f.write() needs a string

Why does f.write(data) fail in Python?

Because f.write() expects a string, but data is a dictionary. Convert it with json.dump() or json.dumps() first.

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

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

Should I open a JSON file with 'w' or 'wb'?

Use 'w' for normal JSON writing in Python. JSON is usually handled as text.

How do I make the JSON file readable for humans?

Use the indent argument:

json.dump(data, f, indent=2)

Can I write a list to a JSON file too?

Yes. JSON supports arrays, so Python lists can also be written using json.dump().

• Python dictionaries — JSON objects map naturally to Python dict values.
• File handling in Python — Writing JSON requires opening, writing, and closing files correctly.
• with statement — This is the safest common pattern for file operations.
• Serialization — Writing JSON is a form of converting in-memory objects into storable text.
• Deserialization — The reverse process when reading JSON back into Python objects.
• json.load() and json.loads() — These are used to read JSON from files or strings.
• Text vs binary files — Understanding file modes helps avoid mistakes like using 'wb' unnecessarily.
• Exception handling — Useful for managing file and serialization errors safely.