Skip to main content

How to Solve "ValueError: unsupported pickle protocol: 5" in Python

The error ValueError: unsupported pickle protocol: 5 occurs when you try to unpickle (deserialize) data that was pickled (serialized) using pickle protocol version 5, but your Python environment doesn't support it. Pickle protocol 5 was introduced in Python 3.8.

This guide explains the cause of the error and provides clear solutions: using the pickle5 backport, lowering the pickle protocol, or upgrading Python.

Understanding Pickle Protocols and the Error​

Python's pickle module is used for serializing (saving) and deserializing (loading) Python objects. Pickle uses different protocols to represent the data. Protocol 5, introduced in Python 3.8, offers performance improvements and support for out-of-band data buffers.

The error "ValueError: unsupported pickle protocol: 5" means:

  • You have a pickled file (or byte stream) that was created using protocol 5 (likely with a Python 3.8+ environment).
  • You are trying to unpickle it using an older Python version (3.7 or earlier) that doesn't understand protocol 5.

Solution 1: Use the pickle5 Backport (for Python 3.5 - 3.7)​

If you can not upgrade your Python installation (e.g., you're on a system with a fixed older Python version), the pickle5 package provides a backport of the protocol 5 features:

pip install pickle5
# or
pip3 install pickle5

Then, replace your import pickle statement with import pickle5 as pickle:

import pickle5 as pickle  # Use pickle5 instead of pickle

# Example: unpickling data that was created with protocol 5
file_path = 'employees.txt'
try:
    with open(file_path, 'rb') as file_obj:
        employee_data = pickle.load(file_obj)  # Use pickle5.load()
        print(employee_data)
except Exception as e:
    print(f"Error unpickling: {e}")
  • import pickle5 as pickle: This imports the backport and makes it available under the name pickle. This way, you don't have to change much of your existing code – just the import statement.
  • The rest of your code that uses pickle.load() and pickle.dump() can stay the same.

Solution 2: Lower the Pickle Protocol (When Creating the Pickle)​

If you have control over the code that creates the pickled data, the best solution is often to use a lower pickle protocol that's compatible with your older Python version. You set the protocol argument in pickle.dump() or pickle.dumps():

import pickle

employee = {
    'first': 'tom',
    'last': 'nolan',
    'salary': '1500'
}

file_path = 'employees.txt'

# Pickle using protocol 4 (compatible with Python 3.4+)
with open(file_path, 'wb') as file_obj:
    pickle.dump(employee, file_obj, protocol=4) # Specify protocol here

# Now, this can be unpickled with Python 3.4 and later:
with open(file_path, 'rb') as file_obj:
    employee_data = pickle.load(file_obj)
    print(employee_data)
  • The default protocol in python 3.7 and earlier is protocol 4, so by setting the protocol argument to 4 you can unpickle it using python 3.4 and later.
  • If you have to make it work with python 2, set the protocol to 2.
  • protocol=4: This tells pickle.dump() to use protocol version 4, which is compatible with Python 3.4 and later.
  • Protocol Choices:
    • protocol=4: Good compatibility with Python 3.4+. Recommended if you need to support older Python 3 versions.
    • protocol=pickle.HIGHEST_PROTOCOL: Uses the highest protocol supported by the current Python interpreter. Avoid this if you need to share the pickled data with older Python versions.

The ideal long-term solution is to upgrade your Python installation to version 3.8 or later. This gives you access to all the new features, performance improvements, and security updates, including native support for pickle protocol 5.

# Check your current version:
python --version  # Or python3 --version, or py --version

If your version is older than 3.8, download the latest version from https://www.python.org/downloads/ and install it.

Table of Contents