How to convert a dict to JSON in Python

The conversion of a Python dictionary to JSON is a fundamental task for data serialization. Python's json module simplifies this process with functions like dumps() for easy data exchange.

In this article, we'll explore several techniques to handle this conversion. We'll cover practical tips, real-world applications, and common debugging advice to help you manage your data effectively.

Using json.dumps() to convert a dictionary to JSON

import json

my_dict = {'name': 'John', 'age': 30, 'city': 'New York'}
json_string = json.dumps(my_dict)
print(json_string)--OUTPUT--{"name": "John", "age": 30, "city": "New York"}

The json.dumps() function is the workhorse for this conversion. It takes a Python object, in this case the dictionary my_dict, and serializes it into a JSON formatted string. This step is crucial for preparing data to be sent over a network or stored in a text based format, as it ensures the data structure is universally understood.

You'll notice the resulting string uses double quotes for all keys and string values, which is a strict requirement of the JSON specification. The function handles this translation automatically, converting the Python dictionary into a valid JSON string that any compliant parser can read.

Basic JSON conversion techniques

The json.dumps() function also includes several useful parameters for improving readability and handling data types that aren't natively serializable.

Converting a dictionary to JSON with custom indentation

import json

my_dict = {'name': 'John', 'age': 30, 'city': 'New York'}
formatted_json = json.dumps(my_dict, indent=4)
print(formatted_json)--OUTPUT--{
"name": "John",
"age": 30,
"city": "New York"
}

For better readability, you can use the indent parameter within json.dumps(). This formats the JSON string—a process often called "pretty-printing"—making it much easier for humans to parse when creating JSON files.

• The integer value you pass, like 4 in the example, sets the number of spaces for each indentation level.
• This is especially helpful for debugging or when you need to manually review the JSON output, as it organizes the data into a clear, nested structure.

Handling non-serializable objects with default parameter

import json
from datetime import datetime

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

my_dict = {'event': 'meeting', 'timestamp': datetime(2023, 5, 15, 14, 30)}
json_string = json.dumps(my_dict, default=convert_datetime)
print(json_string)--OUTPUT--{"event": "meeting", "timestamp": "2023-05-15T14:30:00"}

Sometimes your dictionary contains data types that aren't native to JSON, like datetime objects. Trying to serialize them directly will raise a TypeError. The default parameter in json.dumps() provides a clean solution by letting you pass a function that acts as a custom serializer.

• When json.dumps() encounters a non-serializable type, it calls the function you provided—in this case, convert_datetime.
• The function checks if the object is a datetime instance and converts it into an ISO-formatted string, which JSON can easily handle.

Sorting keys in JSON output with sort_keys

import json

unsorted_dict = {'c': 3, 'a': 1, 'b': 2, 'd': {'z': 26, 'y': 25, 'x': 24}}
sorted_json = json.dumps(unsorted_dict, sort_keys=True, indent=2)
print(sorted_json)--OUTPUT--{
"a": 1,
"b": 2,
"c": 3,
"d": {
"x": 24,
"y": 25,
"z": 26
}
}

The sort_keys parameter gives you control over the order of keys in your JSON output. When you set sort_keys=True, the json.dumps() function arranges the dictionary keys alphabetically. This is incredibly useful for creating consistent, predictable output, which makes comparing JSON objects much easier.

• As you can see in the example, this sorting applies recursively, organizing keys within nested dictionaries as well for a thoroughly ordered result.

Advanced JSON conversion techniques

While the built-in parameters cover common use cases, you'll sometimes need more powerful techniques like custom encoders or faster libraries for complex data serialization.

Working with custom JSON encoders

import json
from decimal import Decimal

class CustomEncoder(json.JSONEncoder):
def default(self, obj):
if isinstance(obj, Decimal):
return float(obj)
return super().default(obj)

my_dict = {'price': Decimal('19.99'), 'qty': 3}
json_string = json.dumps(my_dict, cls=CustomEncoder)
print(json_string)--OUTPUT--{"price": 19.99, "qty": 3}

For more complex serialization, you can create a custom encoder. This approach offers a more structured way to handle non-standard data types compared to just using the default function parameter, especially when your project involves several custom types.

• You start by defining a class that inherits from json.JSONEncoder and then override its default() method.
• Inside default(), you implement the logic to convert specific objects. In this case, it turns a Decimal object into a JSON-compatible float.
• For any other data types, calling super().default(obj) lets the parent encoder handle them, ensuring standard objects still serialize correctly.

To use it, you simply pass your custom encoder class to the cls parameter in json.dumps().

Converting nested dictionaries with complex data types

import json

complex_dict = {
'user': {'name': 'Alice', 'roles': ['admin', 'user']},
'permissions': {'read': True, 'write': True, 'delete': False},
'metadata': {'tags': ('important', 'urgent'), 'priority': 1}
}
json_string = json.dumps(complex_dict, indent=2)
print(json_string)--OUTPUT--{
"user": {
"name": "Alice",
"roles": [
"admin",
"user"
]
},
"permissions": {
"read": true,
"write": true,
"delete": false
},
"metadata": {
"tags": [
"important",
"urgent"
],
"priority": 1
}
}

The json.dumps() function seamlessly handles nested dictionaries, recursively processing the entire data structure without extra setup. It also intelligently converts Python-specific types into their JSON equivalents.

• Python booleans like True and False are automatically mapped to JSON's true and false.
• Python tuples, such as ('important', 'urgent'), are converted into JSON arrays.

This built-in capability simplifies serializing complex, real-world data structures for easy data exchange.

Using orjson for high-performance JSON serialization

import orjson

large_dict = {str(i): i for i in range(1000, 1005)}
json_bytes = orjson.dumps(large_dict, option=orjson.OPT_INDENT_2)
print(json_bytes.decode('utf-8'))--OUTPUT--{
"1000": 1000,
"1001": 1001,
"1002": 1002,
"1003": 1003,
"1004": 1004
}

When performance is a priority, especially with large datasets, you can use a specialized library like orjson. It's designed to be a much faster alternative to Python's built-in json module for serializing data.

• The orjson.dumps() function is the key, but it returns a byte string for maximum efficiency, not a regular text string.
• To view the output or use it as text, you must decode it first, for example, using .decode('utf-8').
• Formatting is handled with options like orjson.OPT_INDENT_2 passed to the option parameter.

Move faster with Replit

Replit is an AI-powered development platform that comes with all Python dependencies pre-installed, so you can skip setup and start coding instantly. This lets you move from learning individual techniques to building complete apps. With Agent 4, you can take an idea to a working product simply by describing what you want to build.

Instead of piecing together functions like json.dumps(), you can ask Agent to build a complete application:

• A configuration manager that takes a Python dictionary and outputs a human-readable JSON file with custom indentation for easy editing.
• An API endpoint that serializes complex data, including custom objects like datetime or Decimal, into a valid JSON response.
• A data validation tool that converts dictionaries into alphabetically sorted JSON strings to create consistent, comparable outputs.

Simply describe your app, and Replit will write the code, test it, and fix issues automatically, all within your browser.

Common errors and challenges

Even with its simplicity, you might run into a few common roadblocks when converting dictionaries to JSON. One of the most frequent issues is a TypeError, which pops up when your dictionary contains a data type that JSON doesn't recognize.

For example, Python set objects are not directly serializable. You have a couple of easy fixes:

• You can convert the set to a list before you call json.dumps().
• Alternatively, you can use the default parameter to pass a function that handles the conversion for you, just as we saw with datetime objects.

Another challenge involves handling special float values like NaN, Infinity, and -Infinity. The official JSON specification doesn't support these values, so trying to serialize them can lead to compatibility issues with other JSON parsers. The most robust solution is to decide how you want to represent them before serialization—you might convert them to null or a specific string to ensure your JSON output is universally compatible.

You may also encounter encoding issues, especially when working with text that includes non-ASCII characters like 'é' or '你好'. By default, json.dumps() escapes these characters, resulting in output like \u00e9. This is valid JSON, but it's not very human-readable. To preserve the original characters, you can set ensure_ascii=False in your function call. Just remember to ensure that wherever you're writing the JSON string is configured to use UTF-8 encoding to prevent a UnicodeEncodeError.

Troubleshooting errors with non-serializable types like set

A frequent cause of a TypeError is trying to serialize a Python set. The json.dumps() function can't process it because the JSON standard doesn't include a native set data type. The following code snippet illustrates what happens when you try.

import json

user_data = {
'name': 'Alice',
'skills': {'Python', 'JavaScript', 'SQL'} # Using a set
}
json_string = json.dumps(user_data)
print(json_string)

When json.dumps() processes the user_data dictionary, it successfully handles the string but stops at the skills key. The function doesn't know how to represent a Python set in JSON, so it raises a TypeError. Let's look at how to resolve this.

import json

user_data = {
'name': 'Alice',
'skills': list({'Python', 'JavaScript', 'SQL'}) # Convert set to list
}
json_string = json.dumps(user_data)
print(json_string)

The fix is straightforward: convert the set into a list before serialization. By wrapping the skills set with list(), you transform it into a data structure that JSON understands as an array. This simple change resolves the TypeError because JSON has a direct equivalent for lists but not for sets. Keep an eye out for this when your data comes from sources that might use sets to store unique items.

Handling NaN and Infinity values in JSON serialization

Serializing special float values like Infinity and NaN can be tricky since they aren't standard in JSON. Attempting to use json.dumps() on a dictionary with these values will result in a ValueError. The following code demonstrates this exact issue.

import json
import math

data = {
'normal_value': 42,
'special_value': float('inf'), # Infinity
'error_value': float('nan') # NaN
}

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

The json.dumps() function hits a ValueError because it can't translate Python's float('inf') and float('nan') values into valid JSON. The following code shows how to properly handle these special cases during serialization.

import json
import math

def serialize_special_floats(obj):
if isinstance(obj, float):
if math.isnan(obj):
return "NaN"
if math.isinf(obj):
return "Infinity" if obj > 0 else "-Infinity"
return obj

data = {
'normal_value': 42,
'special_value': float('inf'),
'error_value': float('nan')
}

json_string = json.dumps(data, default=serialize_special_floats)
print(json_string)

The solution is to provide a custom function to the default parameter in json.dumps(). This function checks for special float values like NaN and Infinity and converts them into strings. This approach neatly sidesteps the ValueError and produces a valid JSON string.

Keep this technique in mind when your data comes from mathematical computations or scientific libraries, as they're common sources for these non-standard float values that can halt serialization.

Resolving encoding errors with non-ASCII characters

Resolving encoding errors with non-ASCII characters

When your dictionary contains non-ASCII characters, such as 'é', json.dumps() escapes them into sequences like \u00e9. While technically valid, this makes the output hard to read. The code below demonstrates this default behavior when writing to a file.

import json

user_info = {
'name': 'José',
'location': 'São Paulo'
}

with open('user.json', 'w') as f:
f.write(json.dumps(user_info))

When writing the output to a file, the default open() function may not use UTF-8 encoding, which can trigger a UnicodeEncodeError. The following code shows how to resolve this and keep your characters readable.

import json

user_info = {
'name': 'José',
'location': 'São Paulo'
}

with open('user.json', 'w', encoding='utf-8') as f:
f.write(json.dumps(user_info, ensure_ascii=False))

The fix is a two-part solution for handling international text. It prevents a UnicodeEncodeError and keeps your JSON output human-readable, which is crucial when your data includes names or locations from different languages.

• Set ensure_ascii=False in json.dumps() to stop Python from escaping non-ASCII characters into sequences like \u00e9.
• Specify encoding='utf-8' when opening the file to ensure it can correctly write those characters.

Real-world applications

Moving beyond the technical details and error fixes, you'll find dictionary-to-JSON conversion at the core of many real-world applications.

Creating a REST API response with json.dumps()

When building a REST API, you'll frequently use json.dumps() to convert your application's data into a clean, structured JSON response for clients.

import json

# Simulate creating a web API response
def generate_api_response():
users = [
{'id': 1, 'name': 'Alice', 'email': 'alice@example.com'},
{'id': 2, 'name': 'Bob', 'email': 'bob@example.com'}
]
response = json.dumps({'status': 'success', 'data': users}, indent=2)
return response

api_response = generate_api_response()
print(api_response)

The generate_api_response function demonstrates a common pattern for structuring API data. It packages the primary data, a list of users, inside a larger dictionary. This outer dictionary also includes metadata, like a status key, which gives the client context about the response.

• The json.dumps() function serializes the entire nested structure into a single JSON string.
• Using indent=2 formats the output, making it easy for developers to read and debug. This is standard practice for creating predictable and well-formed API responses.

Generating GeoJSON for mapping applications

In mapping, json.dumps() is essential for converting Python dictionaries into the GeoJSON format, a standard for encoding geographic data structures.

import json

# Geographic data for map visualization
geo_data = {
'type': 'FeatureCollection',
'features': [
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [-122.4194, 37.7749]
},
'properties': {
'name': 'San Francisco',
'population': 874961
}
},
{
'type': 'Feature',
'geometry': {
'type': 'Point',
'coordinates': [-74.0060, 40.7128]
},
'properties': {
'name': 'New York',
'population': 8336817
}
}
]
}

geo_json = json.dumps(geo_data, indent=2)
print(geo_json)

This code builds a Python dictionary that conforms to the GeoJSON standard, a common format for mapping applications. The structure is key for compatibility with visualization tools.

• The main dictionary is a FeatureCollection, which acts as a container.
• Inside, a list of features defines specific geographic points, each with its own geometry (coordinates) and properties (metadata like name and population).

The json.dumps() function then serializes this complex dictionary into a neatly formatted string, ready for any mapping library to parse and display.

Get started with Replit

Put these techniques into practice by building a real tool. Tell Replit Agent: “Create a config file generator that outputs sorted JSON” or “Build an API that correctly serializes Decimal objects into a JSON response.”

Our AI-powered partner will write the code, test for errors, and deploy your application for you. Start building with Replit.