Python-native caching
Caching computed Python values between process runs.
Python · Module
pickle
pickle serializes Python object hierarchies into binary streams and reconstructs them later. It is Python-specific and must only be used with trusted data because unpickling can execute code.
How it works
The module converts Python object hierarchies to byte streams and reconstructs them later. Use dumps and loads for byte values, or Pickler and Unpickler when file-oriented control is useful; the format is Python-specific and loading can execute code, so only load trusted data.
Syntax
pickle.dump(obj, file, protocol=None, *, fix_imports=True, buffer_callback=None)
pickle.dumps(obj, protocol=None, *, fix_imports=True, buffer_callback=None)
pickle.load(file, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)
pickle.loads(data, /, *, fix_imports=True, encoding='ASCII', errors='strict', buffers=None)Parameters
| Name | Type | Description |
|---|---|---|
obj | object | Object to serialize. |
file | file-like object | Binary file object receiving the pickle. |
data | bytes-like object | Pickle byte stream to deserialize. |
Returns
dumps returns a pickled representation as bytes; loads returns the reconstituted object hierarchy; dump and load operate on file objects.
Key points
- pickle is Python’s standard binary serialization module for turning object structures into streams and back.
- Use dumps when the serialized result should be returned directly as bytes.
- Use loads to reconstruct an object from serialized bytes already held in memory.
- Pickler and Unpickler expose object-oriented control for customized serialization workflows.
- The module defines six protocol levels, allowing applications to balance compatibility and format capabilities.
- The public classes include Pickler, Unpickler, and PickleBuffer.
Common mistakes
- Never unpickle data from an untrusted source because deserialization can execute malicious code.
- Pickles are not a general interchange format; other languages may not be able to reconstruct them.
- Choosing a newer protocol can prevent older Python versions from reading the result.
Example: Persist and restore a Python object
import pickle
from pathlib import Path
record = {"name": "Ada", "roles": ["engineer"]}
path = Path("record.pickle")
with path.open("wb") as file:
pickle.dump(record, file)
with path.open("rb") as file:
restored = pickle.load(file)
assert restored == record
path.unlink()Writes a picklable dictionary to a binary file and restores it with the matching load operation.
When to use it
State persistence
Saving application state when both writer and reader are Python programs.
Trusted internal transfer
Transmitting complex Python object graphs through a trusted internal channel.
Interview questions
QHow do you serialize and deserialize an object with pickle?
Use pickle.dumps(obj) to serialize an object hierarchy to bytes and pickle.loads(data) to reconstruct it. For file-based workflows, pickle.dump(obj, file) and pickle.load(file) provide the corresponding operations.
Follow-up: Why should pickle not be used for untrusted input? Loading a pickle can execute arbitrary code, so the input must be authenticated or otherwise trusted.
QWhat is a pickle protocol?
Pickle supports multiple binary protocols, and the default protocol is designed for compatibility while newer protocols can provide newer capabilities. The protocol choice affects which Python versions can read the resulting stream.
Follow-up: How can you inspect a pickle without loading it? Use pickletools to disassemble and analyze the pickle stream rather than reconstructing its objects.
QWhat kinds of objects can pickle handle?
Pickle can serialize many built-in types, including numbers, strings, bytes, bytearrays, tuples, lists, sets, and dictionaries containing picklable objects. It can also preserve shared references within an object hierarchy.
Follow-up: What commonly prevents an object from being pickled? Objects such as open file handles, sockets, and active execution state generally need to be excluded or represented through custom reduction logic.
Related
pickletoolsPicklerUnpicklerPickleBuffercopyreg