Simplejson

3.20.2 verified Tue May 12 auth: no python install: verified quickstart: verified

Simplejson is a fast, extensible, and standards-compliant JSON encoder/decoder for Python. It's often used as a drop-in replacement for Python's built-in `json` module, offering a C extension for improved performance and additional features. The library is actively maintained, with the current stable version being 3.20.2, and releases occur several times a year.

pip install simplejson

Common errors

error TypeError: Object of type datetime is not JSON serializable ↓

cause Python objects like datetime, sets, or custom classes are not natively convertible into standard JSON types for serialization.

fix

Provide a custom 'default' function to simplejson.dumps() to handle non-serializable types, or convert them to a serializable format (e.g., string for datetime) before serialization.

error simplejson.errors.JSONDecodeError: Expecting value: line 1 column 1 (char 0) ↓

cause The input string is not valid JSON, often because it's empty, malformed, or contains non-JSON content at the beginning.

fix

Ensure the input string is a well-formed JSON document before passing it to simplejson.loads().

error ImportError: No module named 'simplejson' ↓

cause The 'simplejson' package is not installed in the Python environment where the script is being executed.

fix

Install the 'simplejson' package using pip: pip install simplejson.

error AttributeError: module 'simplejson' has no attribute 'dump' ↓

cause Attempting to use `simplejson.dump` (which writes to a file-like object) when `simplejson.dumps` (which returns a JSON string) was intended, or misunderstanding the function signature.

fix

If you want a JSON string, use simplejson.dumps(). If writing to a file, provide a file object as the second argument to simplejson.dump().

Warnings

breaking In versions 3.19.1 and later, security hardening measures changed default behavior to be more strict, consuming and producing only compliant JSON by default. If your application previously relied on non-compliant JSON features being tolerated (e.g., non-string keys if `use_decimal=True`), you might need to adjust your data or explicitly re-enable older, less strict behaviors using specific flags. ↓

fix Review the `simplejson.JSONDecoder` and `simplejson.JSONEncoder` options for flags that can re-enable specific non-compliant behaviors if absolutely necessary, but it's recommended to update your JSON data to be strictly compliant.

gotcha simplejson disables C speedups on specific Python runtimes (e.g., PyPy, GraalPy) where they are not compatible or provide no benefit. If you are using these runtimes, expect equivalent performance to the pure-Python implementation. ↓

fix No fix needed; this is an expected behavior for compatibility and stability on specific runtimes.

gotcha Versions 3.20.0 and 3.20.1 changed key memoization behavior to ensure keys are coerced to strings before memoization. While unlikely to cause direct breaks, if you had highly specific reliance on the internal memoization of non-string keys (e.g., custom objects used as keys that were not string-coerced until later stages), this might subtly alter behavior or performance profiles. ↓

fix Ensure that keys in objects intended for JSON serialization are inherently string-compatible or are handled explicitly. Most common use cases should not be affected.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 18.6M

3.10 alpine (musl) - - 0.01s 18.5M

3.10 slim (glibc) wheel 1.7s 0.01s 19M

3.10 slim (glibc) - - 0.01s 19M

3.11 alpine (musl) wheel - 0.01s 20.6M

3.11 alpine (musl) - - 0.01s 20.4M

3.11 slim (glibc) wheel 1.8s 0.01s 21M

3.11 slim (glibc) - - 0.01s 21M

3.12 alpine (musl) wheel - 0.01s 12.4M

3.12 alpine (musl) - - 0.01s 12.3M

3.12 slim (glibc) wheel 1.5s 0.01s 13M

3.12 slim (glibc) - - 0.01s 13M

3.13 alpine (musl) wheel - 0.01s 12.2M

3.13 alpine (musl) - - 0.01s 11.9M

3.13 slim (glibc) wheel 1.5s 0.01s 13M

3.13 slim (glibc) - - 0.01s 12M

3.9 alpine (musl) wheel - 0.01s 18.1M

3.9 alpine (musl) - - 0.01s 18.0M

3.9 slim (glibc) wheel 2.0s 0.01s 19M

3.9 slim (glibc) - - 0.01s 19M

Imports

simplejson
wrong
```
import json; # only if you've specifically monkey-patched sys.modules['json'] = simplejson
```
correct
```
import simplejson
```
While often used as a drop-in replacement, it is its own module and should be imported as 'simplejson'.
loads
wrong
```
from simplejson import load
```
correct
```
simplejson.loads
```
'load' is for file-like objects, 'loads' is for strings.
dumps
wrong
```
from simplejson import dump
```
correct
```
simplejson.dumps
```
'dump' is for file-like objects, 'dumps' is for strings.

Quickstart verified last tested: 2026-04-23

This quickstart demonstrates encoding a Python dictionary into a formatted JSON string using `simplejson.dumps` and then decoding it back into a Python object using `simplejson.loads`.

import simplejson

data = {'name': 'Alice', 'age': 30, 'is_student': False, 'courses': ['Math', 'Science']}

# Encode Python object to JSON string
json_string = simplejson.dumps(data, indent=4)
print('Encoded JSON:')
print(json_string)

# Decode JSON string to Python object
decoded_data = simplejson.loads(json_string)
print('\nDecoded Data:')
print(decoded_data)
print(f"Accessing a value: {decoded_data['name']}")