Install & Compatibility
Where this runs
tested against v4.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pickle
✓ from zodbpickle import pickle
✗ import pickle
Use this to replace the standard `pickle` module for ZODB compatibility across Python 2 and 3 environments, leveraging `zodbpickle`'s enhancements.
fastpickle
✓ from zodbpickle import fastpickle
Imports the C implementation of `pickle` provided by `zodbpickle` for potentially faster performance.
slowpickle
✓ from zodbpickle import slowpickle
Imports the pure Python implementation of `pickle` from `zodbpickle`.
This quickstart demonstrates basic serialization (pickling) and deserialization (unpickling) of a custom Python object using `zodbpickle.pickle`. It shows how to replace the standard `pickle` import to leverage `zodbpickle`'s specialized features, particularly useful for ZODB environments.
from zodbpickle import pickle
class MyObject:
def __init__(self, name, value):
self.name = name
self.value = value
def __eq__(self, other):
if not isinstance(other, MyObject):
return NotImplemented
return self.name == other.name and self.value == other.value
# Pickle an object
obj = MyObject('example', 123)
pickled_obj = pickle.dumps(obj, protocol=pickle.HIGHEST_PROTOCOL)
print(f"Pickled object (bytes): {pickled_obj}")
# Unpickle the object
unpickled_obj = pickle.loads(pickled_obj)
print(f"Unpickled object: {unpickled_obj.name}, {unpickled_obj.value}")
assert obj == unpickled_obj
Debug
Known issues
breakingThe `pickle` module, and by extension `zodbpickle`, is not intended to be secure against erroneous or maliciously constructed data. Never unpickle data received from an untrusted or unauthenticated source, as it could lead to arbitrary code execution.fixOnly unpickle data from trusted sources. Implement additional security layers if data origin cannot be guaranteed.
affects: All versions
gotchaWhen migrating ZODB databases from Python 2 to Python 3, `Python 2 str` instances are by default loaded as `Python 3 str` (Unicode strings). If these `str` instances contained binary data, this can lead to `UnicodeDecodeError` or incorrect data interpretation. `zodbpickle.binary` was introduced to handle binary strings from Python 2 correctly as `bytes` in Python 3.fixIn Python 2, use `zodbpickle.binary` for storing explicit binary data. When migrating existing Python 2 ZODB databases to Python 3, use migration tools like `zodbupdate` with `--convert-py3` and specify appropriate encoding to convert `str` attributes correctly.
affects: Python 2.x and 3.x interoperability
gotchaWhile `zodbpickle` re-adds the `noload()` method (removed from standard Python 3 `pickle`) for ZODB compatibility, applications might encounter performance differences depending on the `pickle` protocol used. Python 3.4+ introduced `protocol 4` with significant performance impacts (e.g., framing), which standard `pickle` can leverage more directly than `zodbpickle`'s forks of earlier Python 3 `pickle` versions.fixFor ZODB applications, use `from zodbpickle import pickle`. If performance is critical and not tied to ZODB's specific `noload()` requirement, consider profiling with both `zodbpickle.pickle` and the standard `pickle` module to determine the optimal choice for non-ZODB-specific serialization tasks in Python 3.
affects: Python 3.x (especially 3.4+)
Errors
Common errors & fixes
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x... in position ...: invalid start byte
Attempting to unpickle Python 2 `str` data (which could contain arbitrary bytes) in Python 3, where `str` objects are expected to be Unicode. This often occurs during ZODB database migrations.
fixEnsure that Python 2 binary strings were stored using `zodbpickle.binary`. For existing Python 2 ZODB databases, use `zodbupdate --convert-py3 --encoding <your_encoding>` during migration to properly decode and convert string data.
TypeError: can't concat str to bytes
This error typically arises in Python 3 code when attempting to concatenate `str` (Unicode) and `bytes` objects directly. It can be a symptom of incorrect handling of legacy Python 2 data in a ZODB migrated to Python 3, where `zodbpickle.binary` or `bytes` were not used consistently for binary data.
fixExplicitly encode `str` to `bytes` (e.g., `s.encode('utf-8')`) or decode `bytes` to `str` (e.g., `b.decode('utf-8')`) as appropriate before concatenation. Review data handling logic, especially for values originally created in Python 2 or involving `zodbpickle.binary` to ensure type consistency. Upgrade
Version history
4.4latest on PyPI · released May 4, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
ZODBoptionalZODB depends on zodbpickle for its object persistence.