Fix the Python 3 Pickle TypeError

When I first started working with the Python pickle module in Python 3, I ran into a frustrating error:

TypeError: a bytes-like object is required, not 'str'

This error often happens when we try to use pickle in text mode instead of binary mode. It confused me at first, but after a few trials, I figured out the exact cause and how to fix it.

In this tutorial, I’ll share the methods I use to solve this issue. I’ll also walk you through complete code examples so you can avoid the same mistake.

Table of Contents

Why This Error Happens

In Python 3, the pickle module works with binary data, not plain text.
If you open a file in text mode (‘w’ or ‘r’), pickle will throw the error because it expects bytes, not Python strings.

So the fix is simple: always use binary modes like ‘wb’ for writing and ‘rb’ for reading.

Method 1 – Use Binary Mode When Writing

The most common mistake is opening the file in text mode while dumping data. Let me show you how I fixed it.

Wrong Code

import pickle

data = {"state": "California", "population": 39500000}

# This will raise TypeError
with open("usa_data.pkl", "w") as f:
    pickle.dump(data, f)

This code fails because the file is opened in text mode ("w").

Correct Code

import pickle

data = {"state": "California", "population": 39500000}

# Open file in binary write mode
with open("usa_data.pkl", "wb") as f:
    pickle.dump(data, f)

print("Data saved successfully in pickle file.")

You can see the output in the screenshot below.

a bytes-like object is required not list

Now the data is saved without any error.

Method 2 – Use Binary Mode When Reading

The same issue happens when reading pickle files. If you open the file in text mode, Python will complain.

Wrong Code

import pickle

# This will raise TypeError
with open("usa_data.pkl", "r") as f:
    data = pickle.load(f)

Correct Code

import pickle

# Open file in binary read mode
with open("usa_data.pkl", "rb") as f:
    data = pickle.load(f)

print("Loaded data:", data)

You can see the output in the screenshot below.

typeerror a bytes-like object is required not str

This works perfectly and prints the dictionary we saved earlier.

Method 3 – Convert Python Strings to Bytes (Rare Case)

Sometimes, you may already have a string and need to convert it to bytes before using pickle. This usually happens when working with sockets or APIs.

Here’s how I handle it:

import pickle

data = {"city": "New York", "population": 8800000}

# Convert to pickle bytes
pickled_data = pickle.dumps(data)

# Ensure the data is in bytes
print(type(pickled_data))  # <class 'bytes'>

# Later, load it back
loaded_data = pickle.loads(pickled_data)
print("Loaded:", loaded_data)

You can see the output in the screenshot below.

This method is useful when you don’t want to deal with files but just need to serialize and deserialize objects in memory.

Method 4 – Use protocol for Compatibility

When sharing pickle files between different Python versions, I sometimes specify a protocol to avoid encoding issues.

import pickle

data = {"state": "Texas", "population": 29000000}

# Save with protocol 4 for better compatibility
with open("texas.pkl", "wb") as f:
    pickle.dump(data, f, protocol=4)

# Read it back
with open("texas.pkl", "rb") as f:
    new_data = pickle.load(f)

print("Loaded:", new_data)

This ensures the pickle file works across Python 3.x versions without unexpected errors.

Method 5 – Debug Checklist

Whenever I hit this error, I run through this quick checklist:

Did I open the file in binary mode (‘wb’ or ‘rb’)?
Am I using pickle.dumps() / pickle.loads() correctly for in-memory objects?
Do I need to specify a protocol for compatibility?
Am I accidentally writing strings instead of bytes?

This small checklist usually saves me from wasting time.

The error “a bytes-like object is required, not ‘str’” in Python 3 happens because pickle expects binary data.

The fix is simple: always use binary file modes (‘wb’ for writing, ‘rb’ for reading).
If you’re working with strings, convert them to bytes before pickling.

Now that you know these methods, you can confidently use pickle without running into this error again.