Skip to main content

Python library for serializing any arbitrary object graph into JSON

Project description Github Actions BSD


jsonpickle is a library for the two-way conversion of complex Python objects and JSON. jsonpickle builds upon the existing JSON encoders, such as simplejson, json, and ujson.


jsonpickle can execute arbitrary Python code.

Please see the Security section for more details.

For complete documentation, please visit the jsonpickle documentation.

Bug reports and merge requests are encouraged at the jsonpickle repository on github.

jsonpickle officially supports CPython 2.7 and CPython 3.6 or greater. Version support below CPython 3.7 will be dropped upon release of jsonpickle 3.0.

Why jsonpickle?

Data serialized with python’s pickle (or cPickle or dill) is not easily readable outside of python. Using the json format, jsonpickle allows simple data types to be stored in a human-readable format, and more complex data types such as numpy arrays and pandas dataframes, to be machine-readable on any platform that supports json. E.g., unlike pickled data, jsonpickled data stored in an Amazon S3 bucket is indexible by Amazon’s Athena.


jsonpickle should be treated the same as the Python stdlib pickle module from a security perspective.


The jsonpickle module is not secure. Only unpickle data you trust.

It is possible to construct malicious pickle data which will execute arbitrary code during unpickling. Never unpickle data that could have come from an untrusted source, or that could have been tampered with.

Consider signing data with an HMAC if you need to ensure that it has not been tampered with.

Safer deserialization approaches, such as reading JSON directly, may be more appropriate if you are processing untrusted data.


Install from pip for the latest stable release:

pip install jsonpickle

Install from github for the latest changes:

pip install git+

If you have the files checked out for development:

git clone
cd jsonpickle
python develop

Numpy Support

jsonpickle includes a built-in numpy extension. If would like to encode sklearn models, numpy arrays, and other numpy-based data then you must enable the numpy extension by registering its handlers:

>>> import jsonpickle.ext.numpy as jsonpickle_numpy
>>> jsonpickle_numpy.register_handlers()

Pandas Support

jsonpickle includes a built-in pandas extension. If would like to encode pandas DataFrame or Series objects then you must enable the pandas extension by registering its handlers:

>>> import jsonpickle.ext.pandas as jsonpickle_pandas
>>> jsonpickle_pandas.register_handlers()


jsonpickleJS is a javascript implementation of jsonpickle by Michael Scott Cuthbert. jsonpickleJS can be extremely useful for projects that have parallel data structures between Python and Javascript.


Licensed under the BSD License. See COPYING for details. See jsonpickleJS/LICENSE for details about the jsonpickleJS license.


Use make to run the unit tests:

make test

pytest is used to run unit tests internally.

A tox target is provided to run tests using tox. Setting multi=1 tests using all installed and supported Python versions:

make tox
make tox multi=1

jsonpickle itself has no dependencies beyond the Python stdlib. tox is required for testing when using the tox test runner only.

The testing requirements are specified in requirements-dev.txt. It is recommended to create a virtualenv and run tests from within the virtualenv, or use a tool such as vx to activate the virtualenv without polluting the shell environment:

python3 -mvenv env3x
vx env3x pip install --requirement requirements-dev.txt
vx env3x make test

jsonpickle supports multiple Python versions, so using a combination of multiple virtualenvs and tox is useful in order to catch compatibility issues when developing.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jsonpickle-2.2.0.tar.gz (189.9 kB view hashes)

Uploaded source

Built Distribution

jsonpickle-2.2.0-py2.py3-none-any.whl (39.3 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page