pickle

The Python pickle module provides tools to serialize and deserialize Python objects, allowing you to save complex data types to a file and restore them later. This is useful for persisting data or sending Python objects over a network.

Here’s a quick example:

Python
>>> import pickle
>>> data = {"key": "value", "number": 42}

>>> with open("data.pkl", "wb") as file:
...     pickle.dump(data, file)
...

>>> with open("data.pkl", "rb") as file:
...     loaded_data = pickle.load(file)
...

>>> loaded_data
{'key': 'value', 'number': 42}

Key Features

  • Serializes Python objects to a byte stream
  • Deserializes byte streams back to Python objects
  • Supports a wide variety of Python data types, including custom classes
  • Provides different protocols for backward compatibility and efficiency

Frequently Used Classes and Functions

Object Type Description
pickle.dump() Function Serializes an object and writes it to a file
pickle.load() Function Deserializes an object from a file
pickle.dumps() Function Serializes an object to a byte string
pickle.loads() Function Deserializes an object from a byte string
pickle.Pickler Class Provides an interface for serializing Python objects
pickle.Unpickler Class Provides an interface for deserializing Python objects

Examples

Serialize and deserialize a Python object to and from a byte string:

Python
>>> import pickle
>>> data = ["a", "b", "c"]
>>> byte_string = pickle.dumps(data)
>>> byte_string
b'\x80\x04\x95\x07\x00\x00\x00\x00\x00\...'

>>> original_data = pickle.loads(byte_string)
>>> original_data
['a', 'b', 'c']

Common Use Cases

  • Saving and loading application state
  • Caching computations
  • Transmitting Python objects over a network
  • Persisting machine learning models

Real-World Example

Here’s how you can use pickle to save and load user settings:

Python
>>> import pickle

>>> user_settings = {
...     "theme": "dark",
...     "font_size": 14,
...     "show_line_numbers": True
... }

>>> with open("settings.pkl", "wb") as f:
...     pickle.dump(user_settings, f)
...

>>> with open("settings.pkl", "rb") as f:
...     loaded_settings = pickle.load(f)
...

>>> print(loaded_settings)
{'theme': 'dark', 'font_size': 14, 'show_line_numbers': True}

In this example, you use the pickle module to serialize and deserialize the user settings for an app.

Tutorial

The Python pickle Module: How to Persist Objects in Python

In this tutorial, you'll learn how you can use the Python pickle module to convert your objects into a stream of bytes that can be saved to a disk or sent over a network. You'll also learn the security implications of using this process on objects from an untrusted source.

intermediate python

For additional information on related topics, take a look at the following resources:


By Leodanis Pozo Ramos • Updated July 16, 2025