---
id: jsonpickle
version: "4.1.2"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# jsonpickle — jsonpickle encodes/decodes any Python object to/from JSON

License: permissive · Maintenance: active · Downloads: 20.9M/mo

## What it is and what it does

jsonpickle is a serialization library that converts Python objects into JSON format and back again. Unlike Python's built-in pickle module, which produces binary output readable only by Python, jsonpickle generates human-readable JSON that can be indexed and processed by non-Python tools. It handles both simple types and complex structures like numpy arrays and pandas DataFrames through optional registered handlers.

The library sits between pickle's power and JSON's portability: it preserves Python object types and state in a text format suitable for storage, transmission, and cross-platform inspection. However, it carries the same security model as pickle—deserialization can execute arbitrary code, so it should only be used with trusted data sources.

Use it for:

- Serialize machine learning models and numpy arrays to JSON for storage in cloud systems where they can be indexed by query tools.
- Export pandas DataFrames to a human-readable JSON format that remains machine-processable across different platforms and languages.
- Convert complex Python objects to JSON for REST API responses or inter-service communication while preserving type information.
- Store application state or configuration objects as JSON files that can be inspected and debugged without running Python code.
- Migrate data from pickle-based systems to JSON for better tooling support and auditability in data pipelines.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

jsonpickle converts complex Python objects to and from JSON, enabling human-readable serialization of data structures including numpy arrays and pandas DataFrames.

Yes, if you need to serialize complex Python objects to JSON and control the data source. The library is stable, actively maintained, has no external dependencies, and solves a real gap between pickle and standard JSON. However, treat deserialization of untrusted data as a security risk equivalent to pickle—only deserialize data you control or have verified. For untrusted input, read JSON directly without object reconstruction.

## Install

pip install jsonpickle
uv add jsonpickle
poetry add jsonpickle

## Installing jsonpickle

Before you install: Installation is straightforward with no runtime dependencies beyond Python stdlib. The package is actively maintained with a recent release 78 days ago and has 1318 repository stars, indicating stable ongoing support.

License in practice: Licensed under BSD-3-Clause (permissive), allowing commercial and private use with minimal restrictions—you must include the license notice but face no copyleft obligations.

Quickstart:

pip install jsonpickle

import jsonpickle
from dataclasses import dataclass

@dataclass
class Example:
    data: str

ex = Example("value1")
encoded_instance = jsonpickle.encode(ex)
decoded_instance = jsonpickle.decode(encoded_instance)

Only deserialize data from trusted sources; jsonpickle can execute arbitrary Python code during unpickling, just like the stdlib pickle module.

Verify before relying:

- Whether the numpy and pandas extensions require those libraries to be installed separately or are optional at runtime
- Performance characteristics when serializing very large or deeply nested object graphs
- Compatibility guarantees with third-party pickle protocols or custom __getstate__/__setstate__ implementations

## Package facts

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 20.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python object to json serialization, serialize complex python objects, json encoding decoding python, pickle alternative json format, numpy pandas json serialization, human readable python serialization, cross platform object serialization, serialization, json, data-interchange

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