How to create a JSON file in Python

JSON files provide a structured way to store and exchange data in Python. The json module enables seamless conversion between Python objects and JSON format, making it essential for data handling, configuration management, and API interactions.

This guide covers practical JSON file creation techniques, with code examples developed using Claude. You'll learn implementation strategies, best practices, and troubleshooting approaches for your projects.

Creating a JSON file with json.dump()

import json

data = {"name": "John", "age": 30, "city": "New York"}
with open("data.json", "w") as file:
    json.dump(data, file)

# No output, but a data.json file is created with content:
# {"name": "John", "age": 30, "city": "New York"}

The json.dump() function transforms Python dictionaries into JSON format while simultaneously writing to a file. This direct approach eliminates the need for separate conversion and file writing steps, making it more efficient than alternatives.

The method accepts two key parameters: the data structure to serialize and a file object. When working with nested dictionaries or complex data structures, json.dump() automatically handles the conversion of nested Python objects into valid JSON format.

• Automatically manages proper JSON formatting and escaping
• Maintains data type consistency during conversion
• Handles file operations securely through context management

Basic techniques for JSON file creation

Building on the foundational json.dump() method, Python offers additional techniques to handle JSON data with greater flexibility and control over the serialization process.

Using json.dumps() to generate JSON strings

import json

data = {"name": "Alice", "age": 25, "city": "Boston"}
json_string = json.dumps(data)
with open("data_string.json", "w") as file:
    file.write(json_string)

# No output, but a data_string.json file is created with content:
# {"name": "Alice", "age": 25, "city": "Boston"}

The json.dumps() function converts Python objects into JSON-formatted strings, offering a two-step approach to file creation. Unlike json.dump(), this method gives you more control over the JSON string before writing it to a file.

• First, json.dumps() transforms the dictionary into a string that you can manipulate or validate
• Then, the standard file write() method saves the string to your specified file
• This separation enables additional processing or error checking between conversion and file writing

This approach proves particularly useful when you need to modify the JSON string or send it through different channels before saving it to a file. The method maintains the same data type handling and escaping features as json.dump().

Working with nested data structures

import json

user = {
    "name": "Bob",
    "address": {"street": "123 Main St", "city": "Chicago"},
    "hobbies": ["reading", "swimming", "coding"]
}
with open("nested_data.json", "w") as file:
    json.dump(user, file)

# No output, but a nested_data.json file is created with content:
# {"name": "Bob", "address": {"street": "123 Main St", "city": "Chicago"}, "hobbies": ["reading", "swimming", "coding"]}

Nested data structures in JSON allow you to organize complex information hierarchically. The example demonstrates how Python's json.dump() seamlessly handles dictionaries containing other dictionaries and lists.

• The address field contains a nested dictionary with street and city information
• The hobbies field stores an array of strings
• Python automatically maintains the nested structure when converting to JSON format

This hierarchical organization proves especially useful when representing real-world data relationships. The JSON output preserves all levels of nesting while maintaining proper formatting and data type consistency.

Handling file encoding options

import json

data = {"name": "Carlos", "description": "Loves café au lait ☕"}
with open("unicode_data.json", "w", encoding="utf-8") as file:
    json.dump(data, file, ensure_ascii=False)

# No output, but a unicode_data.json file is created with proper UTF-8 encoding:
# {"name": "Carlos", "description": "Loves café au lait ☕"}

When working with non-ASCII characters like emojis or accented letters, proper encoding becomes crucial. The encoding="utf-8" parameter ensures your JSON file correctly handles Unicode characters. Setting ensure_ascii=False allows direct writing of non-ASCII characters instead of converting them to escape sequences.

• UTF-8 encoding supports the full range of Unicode characters while maintaining compatibility with ASCII
• Without proper encoding, special characters might appear corrupted or cause errors when reading the file
• The combination of these parameters creates human-readable JSON files that preserve international characters

This approach proves especially valuable when dealing with multilingual data or content containing emojis and special symbols.

Advanced JSON file handling

Building on the encoding techniques covered above, Python's JSON module provides powerful customization options that give you granular control over file formatting, object handling, and complex data serialization.

Creating formatted JSON with indent and sort_keys

import json

data = {"z": 1, "b": 2, "a": 3, "nested": {"x": 1, "y": 2}}
with open("formatted.json", "w") as file:
    json.dump(data, file, indent=4, sort_keys=True)

# No output, but a formatted.json file is created with content:
# {
#     "a": 3,
#     "b": 2,
#     "nested": {
#         "x": 1,
#         "y": 2
#     },
#     "z": 1
# }

The indent and sort_keys parameters transform your JSON output from a dense, hard-to-read string into a clean, organized format. The indent parameter adds consistent spacing that visually represents the data hierarchy, making nested structures immediately clear.

• indent=4 creates four spaces of indentation for each level of nesting
• sort_keys=True automatically arranges dictionary keys in alphabetical order
• This combination produces JSON files that humans can easily read and maintain

While unformatted JSON works fine for computers, formatted output proves invaluable during development and debugging. The improved readability helps you quickly spot data structure issues or content problems in your JSON files.

Custom object serialization with the default parameter

import json
from datetime import datetime

def serialize_datetime(obj):
    if isinstance(obj, datetime):
        return obj.isoformat()
    raise TypeError("Type not serializable")

data = {"name": "Event", "timestamp": datetime.now()}
with open("custom_objects.json", "w") as file:
    json.dump(data, file, default=serialize_datetime)

# No output, but a custom_objects.json file is created with content:
# {"name": "Event", "timestamp": "2023-04-15T14:30:45.123456"}

The default parameter enables JSON serialization of Python objects that aren't automatically convertible to JSON format. In this example, the serialize_datetime function transforms datetime objects into ISO-formatted strings that JSON can handle.

• The isinstance() check identifies datetime objects and converts them using isoformat()
• Objects that can't be serialized trigger a TypeError
• The default parameter tells json.dump() to use your custom function when it encounters non-standard types

This pattern proves especially useful when working with complex Python objects like dates, custom classes, or specialized data types that need specific serialization rules.

Using JSONEncoder for complex serialization

import json
from datetime import datetime

class CustomEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, datetime):
            return {"__datetime__": obj.isoformat()}
        return super().default(obj)

data = {"event": "Meeting", "when": datetime.now()}
with open("encoder.json", "w") as file:
    json.dump(data, file, cls=CustomEncoder, indent=2)

# No output, but an encoder.json file is created with content:
# {
#   "event": "Meeting",
#   "when": {
#     "__datetime__": "2023-04-15T14:30:45.123456"
#   }
# }

The JSONEncoder class provides a more structured approach to handling complex Python objects during JSON serialization. By subclassing JSONEncoder and overriding its default() method, you gain complete control over how specific object types convert to JSON format.

• The CustomEncoder class specifically targets datetime objects and transforms them into a dictionary with a special key __datetime__
• The super().default(obj) call ensures other Python types still serialize normally
• Using cls=CustomEncoder in json.dump() applies your custom serialization rules to the entire data structure

This approach proves particularly valuable when working with multiple custom types or when you need to preserve type information for later deserialization. The resulting JSON maintains a clear structure that you can easily parse back into Python objects.

Get unstuck faster with Claude

Claude is an AI assistant created by Anthropic that excels at helping developers write, debug, and understand code. It combines deep technical knowledge with natural conversation to provide clear, accurate guidance on programming challenges.

Working alongside you like an experienced mentor, Claude helps you navigate complex JSON operations, resolve encoding issues, or implement custom serialization. It explains concepts thoroughly and suggests practical solutions tailored to your specific needs.

Start accelerating your development process today. Sign up for free at Claude.ai and experience a new way to overcome coding challenges with an AI assistant that understands both code and context.

Some real-world applications

Building on the advanced techniques covered above, Python's JSON capabilities enable practical solutions for everyday development challenges, from configuration management to data exports.

Storing application configuration settings with json.dump()

JSON files provide an elegant solution for storing application settings in a human-readable format, enabling you to maintain configuration data like theme preferences, window dimensions, and user defaults in a structured, easy-to-update file.

import json

app_config = {
    "theme": "dark",
    "font_size": 12,
    "auto_save": True,
    "recent_files": []
}

with open("app_config.json", "w") as config_file:
    json.dump(app_config, config_file, indent=2)

This code creates a configuration file that stores application settings in JSON format. The app_config dictionary contains key settings like theme color, font size, auto-save preferences, and a list for tracking recent files. Using json.dump() with indent=2 writes this data to a file named app_config.json in a clean, readable format.

• The with statement ensures proper file handling and automatic closure
• The indentation parameter creates visually organized output
• Python automatically converts the dictionary's data types into valid JSON format

This approach makes it simple to save and load application settings while maintaining human readability for easy manual edits.

Creating a simple data export tool with json.dump()

The json.dump() function enables you to build data export tools that transform business metrics into structured JSON files—complete with calculated totals and timestamps for tracking.

import json
from datetime import datetime

sales_data = [
    {"product": "Laptop", "units": 5, "price": 1200.00},
    {"product": "Monitor", "units": 10, "price": 300.00},
    {"product": "Keyboard", "units": 15, "price": 80.00}
]

# Calculate total sales for each product
for item in sales_data:
    item["total"] = item["units"] * item["price"]

filename = f"sales_export_{datetime.now().strftime('%Y%m%d')}.json"
with open(filename, "w") as export_file:
    json.dump({"sales": sales_data, "generated_at": datetime.now().isoformat()}, export_file, indent=2)

This code creates a dynamic sales report in JSON format. The script starts with a list of product sales data, where each item contains product details, units sold, and price. It then enhances this data by calculating the total revenue for each product using a simple for loop that multiplies units by price.

The script generates a unique filename that includes today's date using datetime.now().strftime('%Y%m%d'). Finally, it writes the enriched sales data to a JSON file, adding a timestamp with isoformat() to track when the report was created. The indent=2 parameter ensures the output file is properly formatted for easy reading.

• Automatically calculates revenue totals for each product
• Creates date-stamped files for organized record keeping
• Stores data in a structured format that's both human and machine readable

Common errors and challenges

Python's json.dump() function can trigger several common errors that developers encounter when creating JSON files. Understanding these challenges helps you write more reliable code.

Handling non-serializable types with json.dump()

The json.dump() function can't automatically handle Python objects like datetime instances. When you try to serialize these non-JSON-native types, Python raises a TypeError. The following code demonstrates this common pitfall.

import json
from datetime import datetime

event = {"name": "Conference", "date": datetime.now()}
with open("event.json", "w") as file:
    json.dump(event, file)

The json.dump() function raises a TypeError because it encounters a datetime object that it can't convert to JSON's limited data type set. The code below demonstrates an effective solution to this challenge.

import json
from datetime import datetime

event = {"name": "Conference", "date": datetime.now()}
event["date"] = event["date"].isoformat()
with open("event.json", "w") as file:
    json.dump(event, file)

Converting the datetime object to an ISO-formatted string before serialization solves the TypeError. The isoformat() method transforms the datetime into a standardized string representation that JSON can handle. This pattern applies to any Python object that JSON doesn't natively support.

• Watch for this error when working with dates, custom classes, or complex Python objects
• Convert problematic objects to JSON-compatible types before calling json.dump()
• Consider using a custom encoder for more systematic handling of non-serializable types

Fixing incorrect file modes with json.dump()

Opening files in read mode ("r") when attempting to write JSON data triggers a critical io.UnsupportedOperation error. The code below demonstrates this common mistake where developers specify the wrong file mode for json.dump().

import json

user = {"name": "John", "age": 30}
with open("user.json", "r") as file:  
    json.dump(user, file)

The "r" mode opens files for reading only, preventing any write operations. When json.dump() attempts to write data to a read-only file, Python raises an error. Let's examine the corrected version below.

import json

user = {"name": "John", "age": 30}
with open("user.json", "w") as file:  
    json.dump(user, file)

Using "w" mode instead of "r" mode opens the file for writing, allowing json.dump() to successfully write data. The write mode creates a new file if it doesn't exist or overwrites an existing one.

• Always check file modes when working with JSON files
• Use "w" for creating or overwriting files
• Consider "a" mode if you need to append data instead

This error commonly occurs when copying code snippets or switching between file reading and writing operations in your program. Python's error message clearly indicates the issue, making it straightforward to debug.

Handling special characters encoding in json.dump()

When working with non-ASCII characters in JSON files, json.dump() defaults to escaping special characters like accents and currency symbols. This behavior can make your JSON files harder to read and work with. The code below demonstrates this common challenge.

import json

message = {"text": "Café au lait costs €5"}
with open("message.json", "w") as file:
    json.dump(message, file)

The default behavior of json.dump() converts special characters into escaped Unicode sequences, producing JSON that's valid but difficult for humans to read. Let's examine a solution that preserves the original characters.

import json

message = {"text": "Café au lait costs €5"}
with open("message.json", "w", encoding="utf-8") as file:
    json.dump(message, file, ensure_ascii=False)

Setting ensure_ascii=False and specifying encoding="utf-8" preserves special characters in their original form instead of converting them to escaped Unicode sequences. This combination creates more readable JSON files while maintaining full Unicode support.

• Special characters remain human-readable in text editors
• Files stay compatible with systems expecting UTF-8 encoding
• Output size typically decreases without escaped sequences

Watch for this issue when working with international text, emoji, or currency symbols. The default ASCII-only output can make debugging and manual file inspection unnecessarily complex.

Learning or leveling up? Use Claude

Claude combines advanced reasoning capabilities with deep programming expertise to help you tackle JSON challenges more effectively. As your AI pair programming companion, it analyzes your code, suggests improvements, and explains complex concepts in clear, practical terms.

• JSON Structure Review: Ask "What's wrong with my JSON structure?" and Claude will analyze your file format, identify syntax errors, and suggest fixes to ensure valid JSON.
• Encoding Solutions: Ask "How do I handle Unicode characters in my JSON?" and Claude will explain encoding options and provide code examples for proper character handling.
• Custom Serialization: Ask "Can you help me serialize datetime objects?" and Claude will demonstrate different approaches using default functions and custom encoders.
• Error Debugging: Ask "Why am I getting TypeError with json.dump()?" and Claude will diagnose common serialization issues and recommend solutions.
• Best Practices: Ask "How can I make my JSON more readable?" and Claude will share formatting tips and demonstrate proper indentation techniques.

Experience smarter JSON development by signing up for free at Claude.ai today.

For a more integrated development experience, Claude Code brings AI assistance directly to your terminal, enabling seamless collaboration while you work with JSON and other programming tasks.