Implementation:Farama Foundation Gymnasium EzPickle

Knowledge Sources	Farama_Foundation_Gymnasium Gymnasium Docs
Domains	Reinforcement_Learning, Serialization
Last Updated	2026-02-15 03:00 GMT

Overview

A mixin class that enables objects to be pickled and unpickled by storing and replaying their constructor arguments.

Description

The EzPickle class is a lightweight mixin that solves the problem of pickling objects whose internal state is not easily serializable (e.g., environments wrapping C/C++ libraries like MuJoCo or Atari). Instead of attempting to serialize the object's internal state, EzPickle stores the *args and **kwargs passed to its __init__ method. When the object is unpickled, it reconstructs a fresh instance by calling the constructor with the stored arguments.

The implementation provides three methods:

• __init__(*args, **kwargs): Stores the constructor arguments as _ezpickle_args and _ezpickle_kwargs.
• __getstate__(): Returns a dictionary containing only the stored args and kwargs for serialization.
• __setstate__(d): Creates a new instance of the class using the stored args and kwargs, then updates the current instance's __dict__ with the new instance's attributes.

Usage

Use EzPickle as a mixin class when creating environments that wrap non-serializable C/C++ code. Call EzPickle.__init__(self, ...) in the subclass constructor with the same arguments used for initialization. This is commonly needed for MuJoCo, Atari, and JAX-based environments.

Code Reference

Source Location

• Repository: Farama_Foundation_Gymnasium
• File: gymnasium/utils/ezpickle.py

Signature

class EzPickle:
    def __init__(self, *args: Any, **kwargs: Any)
    def __getstate__(self) -> dict
    def __setstate__(self, d: dict) -> None

Import

from gymnasium.utils import EzPickle
# or
from gymnasium.utils.ezpickle import EzPickle

I/O Contract

Inputs

Name	Type	Required	Description
*args	Any	No	Positional arguments passed to the constructor
**kwargs	Any	No	Keyword arguments passed to the constructor

Outputs

Name	Type	Description
__getstate__ return	dict	Dictionary with _ezpickle_args and _ezpickle_kwargs keys

Usage Examples

from gymnasium.utils import EzPickle

class Animal:
    pass

class Dog(Animal, EzPickle):
    def __init__(self, furcolor, tailkind="bushy"):
        Animal.__init__(self)
        EzPickle.__init__(self, furcolor, tailkind)
        self.furcolor = furcolor
        self.tailkind = tailkind

import pickle
dog = Dog("brown", tailkind="curly")
pickled = pickle.dumps(dog)
restored = pickle.loads(pickled)
assert restored.furcolor == "brown"
assert restored.tailkind == "curly"

Related Pages

• Environment:Farama_Foundation_Gymnasium_Python_3_10_Runtime