PettingZoo

1.25.0 · active · verified Thu Apr 16

PettingZoo is a Python library providing a standardized API for multi-agent reinforcement learning (MARL) environments, analogous to Gymnasium for single-agent RL. It offers a wide variety of reference environments and utilities, supporting both sequential (AEC) and simultaneous (Parallel) action paradigms. Currently at version 1.25.0, the library is actively maintained with frequent updates to ensure compatibility with recent Python and Gymnasium versions.

Common errors

```
TypeError: reset() got an unexpected keyword argument 'return_info'
```
cause Attempting to call `env.reset(return_info=True/False)` in PettingZoo versions that have aligned with Gymnasium API, where `return_info` is no longer an argument and info is always returned.

fix Remove the `return_info` argument from `env.reset()`. The `info` dictionary is now always returned implicitly: `observation, info = env.reset()`.
```
AttributeError: 'PettingZooEnv' object has no attribute 'seed'
```
cause Attempting to call `env.seed()` on a PettingZoo environment in versions where this method has been deprecated and removed.

fix Pass the `seed` argument directly to `env.reset()` instead: `env.reset(seed=123)`.
```
AssertionError: Your environment must inherit from the gym.Env class
```
cause Using `stable_baselines3.common.env_checker.check_env` directly on a PettingZoo environment, which implements `AECEnv` or `ParallelEnv` not `gym.Env`.

fix PettingZoo environments are not direct `gym.Env` subclasses. Use `pettingzoo.test.api_test` or `pettingzoo.test.parallel_api_test` to validate PettingZoo API compliance. For integration with `stable_baselines3`, typically a wrapper (like those from `SuperSuit`) is needed to adapt the PettingZoo API.
```
ERROR: This environment does not support render_mode='human'
```
cause The specific environment or its underlying rendering backend does not support the 'human' render_mode, or necessary display dependencies are missing.

fix Check the environment's documentation for supported `render_mode` options. Many environments support `rgb_array` which returns pixel data. Ensure all necessary rendering dependencies (e.g., `pygame`) are installed, potentially via `pip install 'pettingzoo[atari]'` for specific environment families.
```
KeyError: 'agent_id' during agent interaction loop or observation/action space lookup.
```
cause Trying to access an observation or action space for an agent that is no longer active or was never part of `env.agents` or `env.possible_agents`.

fix Always check `if agent in env.agents:` before requesting actions or observations for an agent, especially in environments with variable numbers of agents (e.g., agents can be removed upon 'termination' or 'truncation').

Warnings

breaking Python 3.8 is no longer supported starting from PettingZoo 1.25.0. Ensure your Python environment is 3.9 or higher.
Fix: Upgrade Python to a supported version (3.9, 3.10, 3.11, or 3.12).
deprecated The `pettingzoo.mpe` environments are being transferred to a new dedicated `MPE2` package and will be removed from PettingZoo in a future release.
Fix: Update your imports to `mpe2` (e.g., `from mpe2 import simple_spread_v3`) once the `MPE2` package is stable and available.
breaking The `env.seed()` method has been removed to align with Gymnasium API. Seeding is now handled by the `env.reset()` method.
Fix: Replace calls to `env.seed(seed)` with `env.reset(seed=seed)`.
breaking The `return_info` argument has been removed from `env.reset()`. Info is now always returned as the second element of the tuple, consistent with Gymnasium.
Fix: Remove `return_info=True` or `return_info=False` from `env.reset()` calls. Access info directly from the returned tuple: `observation, info = env.reset(seed=42)`.
breaking The `agent_selector` class was renamed to `AgentSelector` (capitalization change).
Fix: Update imports and references to `AgentSelector` if you are directly using this utility class.
gotcha Windows support is not officially maintained, though PRs related to Windows are accepted. Users on Windows may encounter installation or runtime issues, especially with environment dependencies.
Fix: Prefer Linux or macOS for development. If on Windows, be prepared to troubleshoot environment-specific dependencies (e.g., `cmake`, `swig`).
breaking PettingZoo 1.22.4 was yanked from PyPI due to breaking API changes that were accidentally included. Users on this specific version should upgrade.
Fix: Upgrade PettingZoo to a later stable version (e.g., `pip install pettingzoo>=1.23.0`).

Install

pip install pettingzoo Base Installation
pip install 'pettingzoo[all]' # Install all environment dependencies Full Installation
pip install 'pettingzoo[butterfly]' # Install dependencies for a specific family (e.g., Butterfly) Family-Specific Installation
pip install supersuit # Common companion library for wrappers/preprocessing Install SuperSuit (Optional)

Imports

Environment
```
from pettingzoo.butterfly import pistonball_v6
env = pistonball_v6.env()
```
Environments are imported from their specific family modules (e.g., `atari`, `butterfly`, `classic`, `mpe`, `sisl`) and instantiated via `.env()` for AEC API or `.parallel_env()` for Parallel API.
AECEnv, ParallelEnv
wrong:
```
from pettingzoo import AECEnv, ParallelEnv
```
correct:
```
from pettingzoo.utils.env import AECEnv, ParallelEnv
```
Base environment classes for creating custom environments are located in `pettingzoo.utils.env`.
wrappers
```
from pettingzoo.utils import wrappers
```
Utility wrappers for input validation, stdout capture, etc., provided by PettingZoo itself. SuperSuit provides additional common preprocessing wrappers.
AgentSelector
wrong:
```
from pettingzoo.utils import AgentSelector
```
correct:
```
from pettingzoo.utils.agent_selector import AgentSelector
```
The `AgentSelector` class (renamed from `agent_selector` in v1.25.0) is primarily for internal environment logic or custom environment creation, not for external interaction with `env.agent_iter()`.

Quickstart

This example demonstrates how to initialize and interact with a PettingZoo environment using the Agent-Environment Cycle (AEC) API, which is suitable for turn-based or sequentially acting multi-agent systems. It uses the `pistonball_v6` environment, renders it to a human-readable window, resets it with a fixed seed for reproducibility, and then steps through agents until the episode terminates or truncates.

from pettingzoo.butterfly import pistonball_v6

env = pistonball_v6.env(render_mode="human")
env.reset(seed=42)

for agent in env.agent_iter():
    observation, reward, terminated, truncated, info = env.last()
    if terminated or truncated:
        action = None
    else:
        # In a real scenario, this would be your policy's action
        action = env.action_space(agent).sample() 
    env.step(action)

env.close()

view raw JSON →