Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Files, Paths and Text I/O

The pickle module

Reference for Python's pickle module: serialize almost any object to bytes and back, protocols, what cannot be pickled, and why unpickling untrusted data is unsafe.

The pickle module turns most Python objects into a stream of bytes (pickling) and rebuilds them later (unpickling). It handles custom classes, nested containers, shared references and even cycles, which makes it handy for caching results or passing objects between your own processes.

The format is specific to Python and is not safe for untrusted data. Unpickling can call arbitrary functions, so loading a pickle from a stranger is equivalent to running their code. For data you exchange with other systems or people, use json or another plain data format.

Python
import pickle

blob = pickle.dumps({"a": [1, 2, 3]})
data = pickle.loads(blob)

Try it

Python A round trip

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Limits and danger

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Main functions

Function What it does
pickle.dumps(obj, protocol=None) Returns the pickle as bytes.
pickle.dump(obj, file, protocol=None) Writes the pickle to a file opened in binary mode ("wb").
pickle.loads(data) Rebuilds an object from bytes.
pickle.load(file) Reads one pickle from a binary file ("rb"). Call it repeatedly to read several pickles written one after another.
pickle.HIGHEST_PROTOCOL, pickle.DEFAULT_PROTOCOL The newest protocol version and the one used by default.
pickle.Pickler, pickle.Unpickler Classes for finer control, such as persistent_id or restricting which classes may be loaded.
pickle.PickleError, PicklingError, UnpicklingError Exceptions for failures. Individual unsupported objects usually raise TypeError or PicklingError.

Usage notes

  • Never unpickle data you do not trust, and never unpickle data that could have been modified by someone untrusted (a shared cache directory, a download, a network message). Signing the data with an HMAC before loading is one defense; switching to JSON is the better one.
  • Use binary files. Open with "wb" and "rb". A text-mode file raises an error because pickles are bytes.
  • What is pickled is the instance state, not the code. For a class instance, Python stores the class by its module and name plus the contents of __dict__. The class must be importable under the same name when you load, and __init__ is not called during loading.
  • Cannot be pickled: lambdas and nested functions, generators, open files, sockets, threads and locks, and most objects that wrap operating system resources. Module-level functions and classes pickle by name only.
  • Customize with special methods. __getstate__/__setstate__ control what is saved and restored, and __reduce__ can describe how to rebuild an object from scratch (the hook the trap above abuses).
  • Version compatibility. Newer protocols are faster and more compact but cannot be read by older Python versions. Pass protocol= explicitly when you need to share pickles between versions. Pickles are not a good long-term storage format because renaming a class or module breaks them.
  • Shared references and cycles survive within a single dumps call. Two separate calls produce independent copies.
  • Alternatives: copy.deepcopy() for in-memory copies, json for portable data, sqlite3 for structured storage, shelve for a persistent dictionary (which uses pickle internally and has the same security caveat).