Install & Compatibility
Where this runs
tested against v4.1.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.010s · 18.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.010s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
simplejson
✓ import simplejson
✗ import json; # only if you've specifically monkey-patched sys.modules['json'] = simplejson
While often used as a drop-in replacement, it is its own module and should be imported as 'simplejson'.
loads
✓ simplejson.loads
✗ from simplejson import load
'load' is for file-like objects, 'loads' is for strings.
dumps
✓ simplejson.dumps
✗ from simplejson import dump
'dump' is for file-like objects, 'dumps' is for strings.
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']}")
Debug
Known issues
breakingIn 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.fixReview 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.
affects: >=3.19.1
gotchasimplejson 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.fixNo fix needed; this is an expected behavior for compatibility and stability on specific runtimes.
affects: >=3.20.2 for GraalPy, older for PyPy
gotchaVersions 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.fixEnsure that keys in objects intended for JSON serialization are inherently string-compatible or are handled explicitly. Most common use cases should not be affected.
affects: >=3.20.0
Errors
Common errors & fixes
TypeError: Object of type datetime is not JSON serializable
Python objects like datetime, sets, or custom classes are not natively convertible into standard JSON types for serialization.
fixProvide 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.
simplejson.errors.JSONDecodeError: Expecting value: line 1 column 1 (char 0)
The input string is not valid JSON, often because it's empty, malformed, or contains non-JSON content at the beginning.
fixEnsure the input string is a well-formed JSON document before passing it to `simplejson.loads()`.
ImportError: No module named 'simplejson'
The 'simplejson' package is not installed in the Python environment where the script is being executed.
fixInstall the 'simplejson' package using pip: `pip install simplejson`.
AttributeError: module 'simplejson' has no attribute 'dump'
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.
fixIf you want a JSON string, use `simplejson.dumps()`. If writing to a file, provide a file object as the second argument to `simplejson.dump()`.
Upgrade
Version history
4.1.2latest on PyPI · released Aug 27, 2026
Audit
Dependencies
No dependency data recorded yet.