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
# True

dump 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 input

Catching 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
# False

If 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
# False

For 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' object

Make 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
# 2

Validate 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 schema

Both 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

Related lessons