---
id: json-tricks
version: "3.17.3"
license: Revised BSD License (LICENSE.txt)
license_treatment: permissive
maintenance: active
---

# json-tricks — Extra features for Python's JSON: comments, order, numpy, pandas, datetimes, and many more! Simple but customizable.

License: permissive · Maintenance: active · Downloads: 205.0K/mo

## 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 above — 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

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

- License: Revised BSD License (LICENSE.txt) (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 205.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

json serialization numpy arrays, json with comments python, serialize class instances json, json datetime timezone support, ordered dict json preservation, json-serialization, data-persistence

[View on SkillFed](https://skillfed.io/packages/json-tricks) · [View on PyPI](https://pypi.org/project/json-tricks/)