Serialization with pickle
Published by Brayan K
pickle is Python's built-in serializer: it converts almost any Python object into a stream of bytes you can save or send, and reconstructs the exact object — types and all — when you read those bytes back.
Part of the free Python course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.
Load only bytes whose producer and integrity you trust
Unpickling can execute code. Do not load uploaded pickles, downloaded files of uncertain origin or bytes an untrusted person could replace. Checking the returned object happens after reconstruction, so it cannot make an unsafe load safe. These examples create their own bytes in the same program.
Pickle is useful for trusted Python-specific state, but it does not preserve every resource or promise that old classes will remain compatible forever. The definition above needs those limits. For data exchanged with other programs or untrusted senders, start with a data-only format and validate its structure; Working with JSON owns JSON conversion and its type limitations.
import pickle
original = {"point": (3, 4), "labels": ["draft", "checked"]}
payload = pickle.dumps(original, protocol=4)
restored = pickle.loads(payload)
print(type(payload).__name__)
print(restored == original)
print(restored is original)
print(type(restored["point"]).__name__)
restored["labels"].append("saved")
print(original["labels"])
print(restored["labels"])
# ✅ Expected output:
# bytes
# True
# False
# tuple
# ['draft', 'checked']
# ['draft', 'checked', 'saved']dumps returns bytes; loads reconstructs a graph of objects from those bytes. The restored list is not the original live list. We choose protocol 4 explicitly so the examples use the same supported protocol across the Python versions covered here. A protocol number describes the byte format, not an application’s data schema.
Bytes APIs and file-like APIs have different inputs
import pickle
from io import BytesIO
stream = BytesIO()
pickle.dump({"attempts": 3}, stream, protocol=4)
stream.seek(0)
restored = pickle.load(stream)
print(restored["attempts"])
print(isinstance(stream.getvalue(), bytes))
# ✅ Expected output:
# 3
# Truedump and load operate on binary file-like objects. dumps and loads operate directly on byte values. The s is about an in-memory serialized value, not a text string. Seek back before reading the stream you just wrote. For a real file, use binary modes such as wb and rb; text encoding is not a step in the pickle format.
import pickle
pickle.loads("not bytes")
# ✅ Expected error:
# TypeError: a bytes-like object is required, not 'str'import pickle
pickle.loads(b"")
# ✅ Expected error:
# EOFError: Ran out of inputCatching an error from damaged input does not establish that an input source is trustworthy. Choose the trust boundary before calling loads. Nor is pickle encryption: sensitive values still need appropriate storage protection.
Sharing inside one object graph survives the round trip
import pickle
shared = ["A"]
original = {"left": shared, "right": shared}
restored = pickle.loads(pickle.dumps(original, protocol=4))
restored["left"].append("B")
print(restored["left"] is restored["right"])
print(restored["right"])
print(shared)
# ✅ Expected output:
# True
# ['A', 'B']
# ['A']Pickle remembers objects already visited in the same serialization operation. That preserves aliasing inside the restored graph, while separating it from the original graph. It also supports recursive structures; printing a boolean identity check is clearer than relying on the display of a recursive container.
import pickle
loop = []
loop.append(loop)
restored = pickle.loads(pickle.dumps(loop, protocol=4))
print(restored is restored[0])
print(restored is loop)
# ✅ Expected output:
# True
# FalseIf two objects must preserve shared references, serialize their enclosing graph together. Separate dumps calls have separate memo tables, so loading separately produced payloads does not join their objects into one shared identity.
A class name must still resolve when its state is restored
import pickle
class Note:
def __init__(self, text):
print("initializing")
self.text = text
original = Note("reviewed")
restored = pickle.loads(pickle.dumps(original, protocol=4))
print(restored.text)
print(type(restored) is Note)
print(restored is original)
# ✅ Expected output:
# initializing
# reviewed
# True
# FalseFor this ordinary class, unpickling creates an instance and restores its state without rerunning __init__. Pickle refers to the class by module and qualified name; it does not embed the class’s Python source. In a saved application, define the class at module level in an importable module and keep that definition available when loading. Renaming or moving it can break old files.
Functions are also normally stored by a resolvable name, not by copying their code or closure environment. A nested function or lambda is therefore not a portable substitute for stored data. Open connections and active execution state need their own reconstruction strategy.
import pickle
values = (number * 2 for number in range(3))
pickle.dumps(values, protocol=4)
# ✅ Expected error:
# TypeError: cannot pickle 'generator' objectMake saved state explicit when the class contains temporary data
import pickle
class Report:
def __init__(self, title):
self.title = title
self.cache = {"rendered": "temporary"}
def __getstate__(self):
return {"schema": 1, "title": self.title}
def __setstate__(self, state):
if state["schema"] != 1:
raise ValueError("unsupported report schema")
self.title = state["title"]
self.cache = {}
original = Report("Monthly")
restored = pickle.loads(pickle.dumps(original, protocol=4))
print(restored.title)
print(restored.cache)
print(original.cache["rendered"])
# ✅ Expected output:
# Monthly
# {}
# temporary__getstate__ chooses the stored state, and __setstate__ restores the instance without assuming __init__ just ran. The schema field is an application rule independent of the pickle protocol. This makes compatibility decisions visible, but it still does not make hostile pickle bytes safe: reconstruction code has already been invoked.
Plan how older state will be migrated, rejected or regenerated. A cache that can be recomputed usually needs less compatibility machinery than irreplaceable records. Keep a data-only export when long-term access matters; changing Python classes should not be the only way to recover important information.
Complete a round trip through a binary stream
Fill the in-memory binary stream type, the write operation and the rewind position. Load from the same stream only after moving its cursor back.
import pickle
from io import ___
stream = BytesIO()
pickle.___({"theme": "dark", "retries": 2}, stream, protocol=4)
stream.seek(___)
settings = pickle.load(stream)
print(settings["theme"])
print(settings["retries"])
# 👉 replace ___ with BytesIO
# 👉 replace ___ with dump
# 👉 replace ___ with 0
# ✅ Expected output:
# dark
# 2Validate an application schema after loading a trusted snapshot
Create a trusted snapshot with schema 1 and a tuple of two task dictionaries: A is done and B is pending. Serialize it, restore it, and verify the schema and container types before reporting completed task names. Also test a second locally created snapshot with schema 2 and reject it clearly. Use a separate validate function, and do not describe that post-load check as protection from untrusted pickle code.
import pickle
def validate(snapshot):
if type(snapshot) is not dict or snapshot.get("schema") != 1:
raise ValueError("unsupported task schema")
tasks = snapshot.get("tasks")
if type(tasks) is not tuple:
raise ValueError("tasks must be a tuple")
for task in tasks:
if type(task) is not dict or type(task.get("name")) is not str or type(task.get("done")) is not bool:
raise ValueError("invalid task record")
return tasks
snapshot = {"schema": 1, "tasks": ({"name": "A", "done": True}, {"name": "B", "done": False})}
payload = pickle.dumps(snapshot, protocol=4)
restored = pickle.loads(payload)
print([task["name"] for task in validate(restored) if task["done"]])
print(type(restored["tasks"]).__name__)
try:
other = pickle.loads(pickle.dumps({"schema": 2, "tasks": ()}, protocol=4))
validate(other)
except ValueError as error:
print(str(error))
# ✅ Expected output:
# ['A']
# tuple
# unsupported task schemaBoth payloads were produced here from known data. The validator detects a supported-shape mismatch; it cannot undo arbitrary actions caused by loading an attacker-controlled pickle.
Practice quiz
When should the program decide whether pickle bytes are trusted?
- After inspecting the returned dictionary
- After catching an exception
- Before calling loads or load
- Only after a schema check
Answer: Before calling loads or load. Reconstruction can execute code before a returned value can be validated.
What does this program print? import pickle x = (1, 2) y = pickle.loads(pickle.dumps(x, protocol=4)) print(type(y).__name__) print(y == x)
- tuple True
- list True
- tuple False
- bytes True
Answer: tuple True. Pickle preserves this tuple’s type and values.
What does this program print? import pickle a = [] b = pickle.loads(pickle.dumps([a, a], protocol=4)) print(b[0] is b[1]) print(b[0] is a)
- False False
- True True
- False True
- True False
Answer: True False. Aliasing is preserved within the restored graph, not with the original objects.
What does an ordinary saved class instance require when it is loaded later?
- Its exact original memory address
- A resolvable compatible class definition
- Only the class’s printed name
- A second call to its original constructor
Answer: A resolvable compatible class definition. Class source is not embedded; its module and qualified name must resolve.
What does this program print? import pickle from io import BytesIO s = BytesIO() pickle.dump([2, 4], s, protocol=4) s.seek(0) print(pickle.load(s))
- b"[2, 4]"
- [2, 4]
- (2, 4)
- EOFError
Answer: [2, 4]. The binary stream is rewound before the object is read.
What is the difference between a pickle protocol and an application schema?
- They are two names for the same value
- A schema prevents code execution
- Protocols must match dictionary keys
- Protocol controls byte format; schema controls application data meaning
Answer: Protocol controls byte format; schema controls application data meaning. A supported byte format can still contain state an application no longer understands.
Which error ends this program? import pickle pickle.loads(b"")
- EOFError: Ran out of input
- None
- {}
- TypeError: empty object
Answer: EOFError: Ran out of input. No pickle object is present in an empty byte stream.
Why might __setstate__ initialize a cache explicitly?
- It always runs before __getstate__
- Pickle automatically discards every cache
- Ordinary unpickling does not rerun __init__
- Caches cannot be dictionaries
Answer: Ordinary unpickling does not rerun __init__. Restoration must establish required state without relying on initializer side effects.
Continue this course
- Previous: Time Zones with zoneinfo
- Next: Config Files with configparser — Read and write INI configuration with sections, types, and defaults
- Quick reference: Python cheat sheet