json-tricks

What it is and what it does

json-tricks extends Python's standard json module to serialize and deserialize types that the standard library cannot handle natively. It lets you store arrays in readable format with dtype and shape metadata, save class instances with their module and attribute state, preserve datetime and timezone information as dictionaries, maintain OrderedDict insertion order, and include comments in JSON files by prefixing lines with `#`. Each special type uses a magic key (like `__ndarray__`, `__instance_type__`, `__datetime__`) to signal its type during deserialization.

The package is designed for cases where you need JSON's portability and human readability but work with Python-specific data structures. It supports optional compression for arrays and allows custom serialization via `__json_encode__` and `__json_decode__` methods on your classes. Most features work out of the box, though some require optional dependencies to be installed separately.

Use it for:

• Save arrays to JSON for data interchange while keeping the format human-readable and portable.
• Serialize Python class instances to JSON for configuration files or inter-process communication.
• Store datetime and timezone information in JSON without losing precision or context.
• Preserve dictionary insertion order in JSON files when round-tripping through Python versions.
• Add comments to JSON configuration files for documentation without breaking JSON parsing.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Extends Python's JSON serialization to handle numpy arrays, class instances, datetimes, OrderedDict, comments, and other non-standard types while preserving human readability.

Yes. Low install friction, no runtime dependencies, permissive Revised BSD License, active maintenance, and no known vulnerabilities make it a safe choice. Install it if you need to serialize non-standard Python types to JSON; skip it if you only work with standard JSON types.

Install

json-tricks on PyPI

pip install json-tricks

uv add json-tricks

poetry add json-tricks

Installing json-tricks

Before you install

Low friction install with no runtime dependencies. Actively maintained as of 2026-08-08, with 162 GitHub stars and a stable release history since 2015-11-07.

License in practice

Permissive Revised BSD License allows use in commercial and private projects with minimal restrictions.

Quickstart

pip install json-tricks

from json_tricks import dumps, loads, dump, load, strip_comments

json_str = dumps({'data': [1, 2, 3]})
recovered = loads(json_str)

Optional dependencies (numpy, pandas, pytz) must be installed separately to serialize those specific types.

Verify before relying

• Performance characteristics when serializing very large arrays or deeply nested class hierarchies.
• Current status of pull request and issue handling on the repository.

Package facts

Evidence: json_tricks-3.17.3-py2.py3-none-any.whl

Keywords: json, numpy, OrderedDict, comments, pandas, pytz, enum, encode, decode, serialize, deserialize

Tags

More Python Modules packages