Skip to main content

A rehabilitated, less dangerous pickle.

Project description

pikl README Coverage status PyPI Python versions

This package is an attempt to create a rehabilitated pickle module:

  • GLOBAL and INST opcodes have been removed. The copyreg extension registry is left as the only (opt-in) mechanism to dump or load custom classes.

  • Protocol 0 and 1 support has been removed. Only binary pickles are accepted.

  • Protocol 3 is the default protocol on both Python 2.x and Python 3.x

pikl is derived from zodbpickle, a uniform pickling interface for ZODB.


pikl is ultimately derived from Python’s pickle module. Although efforts have been made to remove identified security vulnerabilities, it is almost certain that more vulneravilities remain.

The pickle module is not intended to be secure against erroneous or maliciously constructed data. Never unpickle data received from an untrusted or unauthenticated source as arbitrary code might be executed.

Also see

General Usage

To use pikl instead of Python’s inbuilt pickle module, replace:

import pickle


import pikl.pickle as pikl

This provides compatibility, but has the effect that you get the fast implementation in Python 3, while Python 2 uses the slow version.

To get a more deterministic choice of the implementation, use one of:

import pikl.fastpickle as pikl # always C
import pikl.slowpickle as pikl # always Python

A bytestream produced by pickle can by loaded by pikl provided it meets certain restrictions (e.g. protocol >= 2, no use of GLOBAL opcode):

$ python3
>>> import pickle
>>> s = pickle.dumps({'abc': 2})
>>> from pikl import pickle as pikl
>>> pikl.loads(s)
{'abc': 2}

Loading an earlier protocol will raise UnpicklingError:

>>> s = pickle.dumps({'abc': 2}, protocol=0)
>>> pikl.loads(s)
Traceback (most recent call last):
pikl.pickle_3.UnpicklingError: Only binary pickle protocols are supported

Loading an unregistered class or callable will raise UnpicklingError:

>>> s = pickle.dumps(complex(2, 1))
>>> pikl.loads(s)
Traceback (most recent call last):
pikl.pickle_3.UnpicklingError: GLOBAL opcode is not supported

Extension Registry

To provide an opt-in mechanism for loading classes or callables pikl uses the extension registry in the copyreg module:

>>> import copyreg
>>> copyreg.add_extension('builtins', 'complex', 240)
>>> s = pickle.dumps(complex(2, 1))
>>> pikl.loads(s)

Both the pickler and unpickler must agree on the same registry codes. A future version of pikl will include a mechanism (e.g. defined profiles) to make this assist.


0.0.1 (2018-09-26)

  • Forked from zodbpickle 1.0.3

  • Remove support for pickle protocol 0 and 1

  • Remove support for DUP opcode

  • Remove support for GLOBAL opcode

  • Remove support for INST opcode

  • Add pickle.LOWEST_PROTOCOL and cPickle.LOWEST_PROTOCOL constants

Download files

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

Source Distribution

pikl-0.0.1.tar.gz (173.0 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page