`copyreg`

The Python copyreg module provides a registry for defining custom pickling functions for specific object types. Both the pickle and copy modules consult this registry when serializing or copying objects, making copyreg the standard mechanism for adding pickle support to types that cannot be pickled by default:

>>> import copyreg, pickle
>>> class Point:
...     def __init__(self, x, y):
...         self.x, self.y = x, y
...
>>> def pickle_point(p):
...     return Point, (p.x, p.y)
...
>>> copyreg.pickle(Point, pickle_point)
>>> pt = Point(3, 4)
>>> pickle.loads(pickle.dumps(pt)).x
3

Key Features

Registers a custom reduction function for any type with copyreg.pickle()
Validates callable constructors with copyreg.constructor()
Exposes a module-level dispatch_table dictionary mapping types to their reduction functions
Integrates with both the pickle and copy modules without additional configuration
Supports per-type customization without modifying the original class

Frequently Used Classes and Functions

Object	Type	Description
`copyreg.pickle()`	Function	Registers a reduction function for objects of a given type
`copyreg.constructor()`	Function	Declares a callable as a valid constructor for reconstructing objects
`copyreg.dispatch_table`	Dictionary	Maps types to their registered reduction functions

Examples

Using the copy module with a registered reducer:

>>> import copyreg, copy
>>> class Color:
...     def __init__(self, name):
...         self.name = name
...
>>> def pickle_color(c):
...     return Color, (c.name,)
...
>>> copyreg.pickle(Color, pickle_color)
>>> copy.copy(Color("blue")).name
'blue'

Inspecting the dispatch table to confirm a type is registered:

>>> import copyreg
>>> class Token:
...     def __init__(self, value):
...         self.value = value
...
>>> def pickle_token(t):
...     return Token, (t.value,)
...
>>> copyreg.pickle(Token, pickle_token)
>>> Token in copyreg.dispatch_table
True

Common Use Cases

The most common tasks for copyreg include:

Adding pickle support to C extension types that lack built-in serialization
Controlling how objects are reconstructed when loaded from pickled data
Supporting cross-version compatibility by defining stable reconstruction functions
Enabling custom objects to be passed between processes in multiprocessing workflows
Registering reducers for third-party types without modifying their source code

Real-World Example

When using Python’s multiprocessing module, worker processes receive objects through pickle. Registering a reduction function with copyreg ensures that a custom configuration object survives the process boundary intact:

import copyreg
import multiprocessing

class Config:
    def __init__(self, host, port):
        self.host = host
        self.port = port

def pickle_config(cfg):
    return Config, (cfg.host, cfg.port)

copyreg.pickle(Config, pickle_config)

def process_task(cfg):
    return f"Connected to {cfg.host}:{cfg.port}"

if __name__ == "__main__":
    cfg = Config("localhost", 8080)
    with multiprocessing.Pool(2) as pool:
        results = pool.map(process_task, [cfg, cfg])
    print(results)

Run it:

$ python worker.py
['Connected to localhost:8080', 'Connected to localhost:8080']

The reduction function pickle_config returns the class and the arguments needed to reconstruct a Config instance, giving multiprocessing a reliable way to pass the object to each worker process.

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: