How to Use pickle in Python
In Python, the pickle module allows you to serialize Python objects into binary format and save them to a file, or deserialize binary data back into original objects.
The process of converting objects into binary is called pickling. Conversely, converting binary data back into objects is called unpickling.
As discussed later, unpickling data from untrusted sources is dangerous and should be avoided.
Note that NumPy provides its own methods for saving and loading data in binary formats.
All sample code in this article assumes that the pickle module has been imported. No additional installation is required since it is included in the standard library.
import pickle
Save and load files with pickle
pickle.dump()
To serialize and save an object to a file, use pickle.dump().
The first argument is the object to serialize, and the second argument is a file object.
You can get a file object by opening a file with the built-in open() function, specifying 'wb' (write + binary) mode.
d = {'int': 100, 'bool': False, 'list': [0, 1, 2]}
with open('data/temp/my_dict.pkl', 'wb') as f:
pickle.dump(d, f)
While there’s no strict requirement for the file extension, .pkl or .pickle is commonly used.
pickle.load()
To load a pickled file and restore the original object, use pickle.load().
Use the file created in the previous pickle.dump() example.
Pass the file object as the first argument, opening it in 'rb' (read + binary) mode.
with open('data/temp/my_dict.pkl', 'rb') as f:
d_load = pickle.load(f)
print(d_load)
# {'int': 100, 'bool': False, 'list': [0, 1, 2]}
Serialize and deserialize objects as bytes
pickle.dumps()
To serialize an object into a bytes object (rather than saving it directly to a file), use pickle.dumps().
b = pickle.dumps(d)
print(b)
# b'\x80\x04\x95&\x00\x00\x00\x00\x00\x00\x00}\x94(\x8c\x03int\x94Kd\x8c\x04bool\x94\x89\x8c\x04list\x94]\x94(K\x00K\x01K\x02eu.'
print(type(b))
# <class 'bytes'>
pickle.loads()
To restore an object from a pickled bytes object, use pickle.loads().
Use the bytes object created in the previous pickle.dumps() example.
d_loads = pickle.loads(b)
print(d_loads)
# {'int': 100, 'bool': False, 'list': [0, 1, 2]}
Pickle protocol versions
As of Python 3.13, there are six pickle protocol versions, numbered from 0 to 5. For details, refer to the official documentation:
You can specify the protocol version with the protocol argument in pickle.dump() (third argument) or pickle.dumps() (second argument). If omitted, the default protocol (4 as of Python 3.13) will be used.
When using pickle.load() or pickle.loads(), the protocol is automatically detected, so no specification is needed.
Be aware that if you try to unpickle a file created with a newer protocol on an older version of Python, you may encounter compatibility issues.
Fortunately, protocol 4 has been supported since Python 3.4, so unless you're working with a very old environment, there should be no issues. Protocol 5, the newest version, is supported starting from Python 3.8.
Pros and cons of pickle
Data structures like dictionaries and lists can also be saved and loaded as JSON.
In the example below, an object is converted to a JSON string and then parsed back, confirming that the original structure is preserved.
import json
d = {'int': 100, 'bool': False, 'list': [0, 1, 2]}
j = json.dumps(d)
d_json_loads = json.loads(j)
print(d_json_loads)
# {'int': 100, 'bool': False, 'list': [0, 1, 2]}
However, types like set or complex cannot be handled with JSON.
d['set'] = {0, 1, 2}
d['complex'] = 1 + 2j
# j = json.dumps(d)
# TypeError: Object of type set is not JSON serializable
Pickle, on the other hand, can serialize these types and many others, making it one of its major advantages.
b = pickle.dumps(d)
d_pickle_loads = pickle.loads(b)
print(d_pickle_loads)
# {'int': 100, 'bool': False, 'list': [0, 1, 2], 'set': {0, 1, 2}, 'complex': (1+2j)}
On the downside, JSON is a widely used text format that can be handled by many applications, while pickle is a Python-specific binary format, limiting its portability.
Finally, as explained later in this article, pickle also has security vulnerabilities, particularly during unpickling.
Important notes about Pickle
Pickling functions, classes, and instances
In Python, functions and classes are objects, and they can be pickled. However, only their names are serialized—not their code or associated data.
When pickling class instances, the instance’s attributes are preserved, but not the code defining the class.
For example, consider the following class and its instances:
class MyClass:
def my_func(self):
print('This is MyClass.')
mc = MyClass()
mc.a = 100
If you unpickle within the same script where the class is still defined, the instance can be restored successfully.
b = pickle.dumps(mc)
mc_loads = pickle.loads(b)
mc_loads.my_func()
# This is MyClass.
print(mc_loads.a)
# 100
However, if the original class definition is missing (for example, deleted with del or simply not available in a different script), pickle.load() or pickle.loads() will fail.
del MyClass
# mc_loads = pickle.loads(b)
# AttributeError: Can't get attribute 'MyClass' on <module '__main__'>
You can redefine a class with the same name to unpickle the object, but if the redefined class has different code, that code will be used. The instance’s stored attribute values will remain unless explicitly updated.
class MyClass:
def my_func(self):
print('This is the newly defined MyClass.')
mc_loads = pickle.loads(b)
mc_loads.my_func()
# This is the newly defined MyClass.
print(mc_loads.a)
# 100
Thus, when pickling and unpickling class instances, it's essential that the corresponding class is properly defined and matches the original.
Pickle also provides mechanisms for finer control over how instances are serialized and deserialized. For details, see:
- pickle - Pickling Class Instances — Python 3.13.3 documentation
- pickle - Custom Reduction for Types, Functions, and Other Objects — Python 3.13.3 documentation
Security risk when unpickling
As the official documentation warns, pickle is not secure. It is possible for a specially crafted pickle file to execute arbitrary code during unpickling.
Warning: The pickle module is not secure. Only unpickle data you trust.
It is possible to construct malicious pickle data which will execute arbitrary code during unpickling. Never unpickle data that could have come from an untrusted source, or that could have been tampered with. pickle — Python object serialization — Python 3.13.3 documentation
Never unpickle data unless you are absolutely sure of its source and integrity.