Install & Compatibility
Where this runs
tested against v3.17.3 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.060s · 18MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 1.5s · import 0.055s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
json_tricks
✓ import json_tricks
✗ import json_tricks.numpy
Since version 3.x, the numpy and pandas functionalities are integrated into the main json_tricks module, making direct imports of submodules like json_tricks.numpy unnecessary.
dumps
✓ json_tricks.dumps
✗ json_tricks.numpy.dumps
The top-level `dumps` function in `json_tricks` automatically handles NumPy arrays and other extended types when installed with optional dependencies.
loads
✓ json_tricks.loads
✗ json.loads
To correctly deserialize objects encoded with `json_tricks` (especially with metadata or comments), always use `json_tricks.loads`.
This quickstart demonstrates how to serialize and deserialize data containing NumPy arrays, datetime objects, and Pandas DataFrames using `json_tricks.dumps` and `json_tricks.loads`. It highlights the importance of `store_python_metadata=True` for successful round-tripping of complex types.
import json_tricks
import numpy as np
import datetime
import pandas as pd
# Example data with extended types
data = {
'numbers': np.array([1, 2, 3]),
'timestamp': datetime.datetime.now(),
'dataframe': pd.DataFrame({'a': [1, 2], 'b': [3, 4]}),
'mixed_list': [1, 'text', {'key': True}],
'comments_example': '// This is a comment inside JSON' # Will be stripped unless allow_comments is used in dump
}
# Dump to a JSON string with metadata to enable full round-tripping
json_string = json_tricks.dumps(data, indent=4, store_python_metadata=True)
print('--- Dumped JSON ---')
print(json_string)
# Load from the JSON string
loaded_data = json_tricks.loads(json_string)
print('\n--- Loaded Data ---')
print(loaded_data)
# Verify types were restored
print(f"Type of 'numbers': {type(loaded_data['numbers'])} ")
print(f"Content of 'numbers': {loaded_data['numbers']}")
print(f"Type of 'timestamp': {type(loaded_data['timestamp'])}")
print(f"Type of 'dataframe': {type(loaded_data['dataframe'])}")
Debug
Known issues
gotchaFor `json-tricks` to properly restore complex Python objects (like custom classes, NumPy arrays, Pandas DataFrames, or datetimes) to their original types upon deserialization, you must pass `store_python_metadata=True` to the `json_tricks.dumps` function. Without it, these objects might be loaded as generic lists, dictionaries, or strings.fixAlways use `json_tricks.dumps(data, store_python_metadata=True)` when serializing complex Python objects that need to be fully restored.
affects: All versions
breakingBefore version 3.x, you might have imported specific submodules like `json_tricks.numpy` or `json_tricks.pandas` to access their enhanced serialization. Since version 3.x, these functionalities are directly integrated into the main `json_tricks` module, making the submodule imports largely obsolete and potentially leading to `AttributeError`.fixSimply `import json_tricks` and use `json_tricks.dumps`/`loads` directly. Ensure `numpy` and `pandas` are installed if you intend to use their serialization features.
affects: < 3.0.0 (transition to 3.x and newer)
gotchaWhile `json-tricks` supports comments in JSON, standard Python's `json` module does not. If you dump JSON with comments using `json_tricks.dumps(..., allow_comments=True)` and then attempt to load it with `json.loads` or `json.load`, it will raise a `json.JSONDecodeError`.fixAlways use `json_tricks.loads` to load JSON that may contain comments, as it is designed to parse them correctly.
affects: All versions
gotchaLoading JSON from untrusted sources with `store_python_metadata=True` or custom `extra_obj_hooks` can lead to arbitrary code execution. `json-tricks` can dynamically instantiate objects based on metadata, which is a security risk if malicious data is provided.fixOnly load JSON generated by trusted sources. If you must load untrusted JSON, disable `store_python_metadata=True` and avoid using `extra_obj_hooks` or `ignore_errors=False` (which allows calling `__init__` for unknown types).
affects: All versions
Errors
Common errors & fixes
TypeError: Object of type <class 'your_module.CustomClass'> is not JSON serializable
You are attempting to serialize a custom Python object that `json-tricks` doesn't know how to handle by default, and you haven't provided custom serialization methods (`__json_encode__`, `__json_decode__`) or enabled metadata storage.
fixDefine `__json_encode__(self)` and `__json_decode__(cls, **kwargs)` methods in your custom class. Then, ensure you call `json_tricks.dumps(your_object, store_python_metadata=True)`.
AttributeError: module 'json_tricks' has no attribute 'numpy'
You are trying to access the `numpy` submodule (e.g., `json_tricks.numpy`) in version 3.x or newer of `json-tricks`. This submodule access is deprecated and its functionality is now integrated directly into the main module.
fixRemove the `.numpy` (or `.pandas`) from your imports and function calls. Simply use `import json_tricks` and then `json_tricks.dumps` or `json_tricks.loads`. Ensure `numpy` is installed.
json.JSONDecodeError: Expecting value: line X column Y (char Z)
This error typically occurs when you try to load JSON that contains C-style comments (which `json-tricks` supports) using Python's standard `json.loads` or `json.load` function, which does not understand comments.
fixUse `json_tricks.loads` (or `json_tricks.load` for files) instead of `json.loads`. `json_tricks` is designed to correctly parse JSON containing comments.
Upgrade
Version history
3.17.3latest on PyPI · released Aug 19, 2023
Audit
Dependencies
numpyoptionalRequired for native serialization/deserialization of NumPy arrays.
pandasoptionalRequired for native serialization/deserialization of Pandas DataFrames and Series.