Python json.dumps() Complete Guide with Examples

To dump a Python object to JSON string, you can use the json.dumps() method of the built-in json module. The json.dump() paired method (without the "s") converts the Python object to JSON string and writes it to a file. By passing indent and sort_keys parameters to the json.dumps() and json.dump() methods, you can pretty-print the result JSON, otherwise, a compact JSON will be generated. If your Python object contains a non-basic objects, the json.dumps() method will throw an exception. By passing the skipkeys=True, you can tell json.dumps() to ignore such objects instead of throwing an exception. In this Python JSON Dumps example, we are serializing a basic Python object to a JSON string. More advanced Python to JSON examples are listed below. Click Execute to run the Python JSON Dumps example online and see the result.
Python json.dumps() Complete Guide with Examples Execute
import json

obj = {
  "Id": 78912,
  "Customer": "Jason Sweet",
  "Quantity": 1,
  "Price": 18.00
}

json_str = json.dumps(obj, indent=4)
      
print(json_str)
Updated: Viewed: 4557 times

What is JSON?

JSON (JavaScript Object Notation) is a standard textual format for representing structured data using JavaScript syntax. Data presented in JSON format is much smaller than XML and is easier to read by humans and computers. JSON is widely used by mobile and web applications for exchanging and storing data. JSON is used in almost every scripting language, including JavaScript, Java, Python, C ++, C #, Go, PHP, and many more.

JSON Example
{
  "Id": 78912,
  "Customer": "Jason Sweet",
  "Quantity": 1,
  "Price": 18.00
}

How to work with JSON in Python?

Python has a built-in module called json (JSON Encoder and Decoder) for working with JSON. To work with JSON in Python, you need to import the json module first.

Basic json.dumps() Example
import json

json_str = json.dumps({"Id": 78912})
        
print(json_str)

# output: {"Id": 78912}

What is Python Object Serialization?

Serialization is the process of converting (encoding) Python objects into a stream of bytes (or string) to store the object in a database or file or transfer it over a network. The primary purpose of serialization is to preserve the state of an object so that it can be recreated in exactly the same state if needed. Serialization itself is insecure, and Python objects containing sensitive data must be additionally protected and transmitted only over secure network connections.

How does JSON Encoder convert Python object to JSON string?

Since JSON is an independent data storage format and comes from the JavaScript world, it has different data types than Python. The JSON Encoder only supports the following basic types and data structures and will throw an exception for other Python object types:

Python JSON
dict object
list, tuple array
str string
int, float number
True true
False false
None null

How to serialize complex Python objects?

If the JSON Encoder encounters a non-base Python object, it will throw a TypeError exception when converting the Python object to a JSON string. The code below will raise a "TypeError: Object of type Point is not JSON serializable" exception because of the json.dumps() method does not know how to serialize a Point class object to a JSON string. We will show below how to fix this error and teach json.dumps() method to work with complex Python objects.

The json.dumps() throws exception for complex Python objects
import json

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

json_str = json.dumps(Point(1, 2))

print(json_str)

# output: TypeError: Object of type Point is not JSON serializable

Serializing complex Python objects to JSON with the json.dumps() method

The json module provides an extensible API for encoding (or dumping) basic Python objects into JSON data strings and decoding (or parsing) JSON data strings into Python objects. The JSON dump method takes an optional cls parameter to pass your own JSON encoder implementation. The custom JSON encoder will be used for Python to JSON conversions instead of the base JSONEncoder class.

Dump Python to JSON using custom JSON encoder class
import json

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

class PointEncoder(json.JSONEncoder):
    def default(self, obj):
            return [obj.x, obj.y]

json_str = json.dumps(Point(1, 2), cls=PointEncoder)

print(json_str)

# output: [1, 2]

As you can now see, json.dumps() does not throw an exception and converts the non-basic object to a JSON string.

Python to JSON Dump Method Syntax

The json.dumps() syntax
json.dumps(obj, *, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, default=None, sort_keys=False, **kw)

Where:
  • skipkeys - when True, then do not throw a TypeError for non-basic types (skip these objects)
  • ensure_ascii - when True, escape all non-ASCII characters
  • indent - if specified then pretty-print JSON with that indent level
  • separators - separators to use when generating JSON output. To get a compact JSON use (',', ':').
  • sort_keys - if True, then dictionaries are sorted by key

How to dump a Python object to a JSON file?

To serialize a Python object to a JSON file, you can use the json.dump() method (without the "s") from the json module. The json.dump() method is similar to json.dumps(), but it takes an additional File Pointer (fp) object and outputs the generated JSON to that file. The fp.write() method must support str input as the json module creates strings (not bytes).

Dump Python object to a JSON file example
import json

with open('data.json', 'w') as fp:
    json.dump({"Id": 78912}, fp)

How to pretty print the JSON using json.dumps()?

You can pretty-print the JSON output by specifying the indent level to the json.dumps() method.

Pretty print JSON output example
import json

json_str = json.dumps({"Id": 78912}, indent=4)

print(json_str)

# output:
# {
#    "Id": 78912
# }

How to get compact JSON output using json.dumps()?

To get a compact JSON without spaces or line breaks, you can pass the separators==(',', ':') to the json.dumps() method and avoid using the indent.

Serialize Python object to compact JSON example
import json

json_str = json.dumps({"Id": 78912}, separators=(',', ':'))

print(json_str)

# output: {"Id":78912}

How to sort data in JSON using json.dumps()?

To sort the data in the generated JSON string, pass the sort_keys=True parameter to the json.dumps() method.

Dump Python object to sorted JSON example
import json

json_str = json.dumps({"b": "b_val", "c": "c_val", "a": "a_val"}, sort_keys=True)

print(json_str)

# output: {"a": "a_val", "b": "b_val", "c": "c_val"}

How can I prevent json.dumps() from throwing exceptions?

If the Python dictionary contains a non-basic object, json.dumps() method will throw a TypeError exception by default. To prevent json.dumps() from throwing exceptions, pass the skipkeys=True parameter to the json.dumps() method. This will tell json.dumps() to ignore such keys.

Prevent json.dumps() from throwing an exception
import json

class User:
    def __init__(self, name, surname):
        self.name = name
        self.surname = surname
    
    
user = User('name', 'surname')
    
test_dict = {User: user, "key": "value"}
    
json_str = json.dumps(test_dict, skipkeys=True)
    
print(json_str)

# output: {"key": "value"}

How to handle non-ASCII characters when using json.dumps()?

By default, the json.dumps() method will escape all non-ASCII characters in the resulting JSON. To force the json.dumps() method to store non-ASCII characters in JSON, pass sure_ascii=False to the json.dumps() call. Note that this may break the JSON and prevent some clients from reading it.

Escaping non-ASCII characters example
import json

unicode_string = u"\u00f3"

print(json.dumps(unicode_string, ensure_ascii=True))
print(json.dumps(unicode_string, ensure_ascii=False))

# output: \u00f3
# output: ó

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

The json.loads() method is the opposite of json.dumps(). It takes a JSON string and converts it to a Python object, while json.dumps() takes a Python object and converts it to a JSON string. Use the json.loads() method to parse JSON strings and files and convert them into Python objects.

Convert JSON string to Python object example
import json

json_str =  '{ "Id": "12345"}'
              
data = json.loads(json_str)
              
print(data["Id"])
        
# output: 12345

Conclusion

The json.dumps() method allows you to dump Python objects to JSON strings in a simple and elegant way. The json.dumps() method is very flexible; you can pretty-print the generated JSON strings or create compact JSON files. The json.dumps() method has a rich set of options for handling non-ASCII characters, sorting JSON keys, and working with floating-point numbers, and can be easily extended with custom JSON encoders.

See also