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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
sky cloud water forest falcon rock
This is the words.txt file.
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.
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.
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.
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.
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.
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
List all Python tutorials.