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.
import pickle blob = pickle.dumps({"a": [1, 2, 3]}) data = pickle.loads(blob)
Try it
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.
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
dumpscall. Two separate calls produce independent copies. - Alternatives:
copy.deepcopy()for in-memory copies,jsonfor portable data,sqlite3for structured storage,shelvefor a persistent dictionary (which uses pickle internally and has the same security caveat).