{"id":7498,"library":"pettingzoo","title":"PettingZoo","description":"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.","status":"active","version":"1.25.0","language":"en","source_language":"en","source_url":"https://github.com/Farama-Foundation/PettingZoo","tags":["reinforcement-learning","multi-agent","gymnasium","ai","environments","deep-learning"],"install":[{"cmd":"pip install pettingzoo","lang":"bash","label":"Base Installation"},{"cmd":"pip install 'pettingzoo[all]' # Install all environment dependencies","lang":"bash","label":"Full Installation"},{"cmd":"pip install 'pettingzoo[butterfly]' # Install dependencies for a specific family (e.g., Butterfly)","lang":"bash","label":"Family-Specific Installation"},{"cmd":"pip install supersuit # Common companion library for wrappers/preprocessing","lang":"bash","label":"Install SuperSuit (Optional)"}],"dependencies":[{"reason":"Supported versions: 3.9, 3.10, 3.11, 3.12","package":"python","optional":false},{"reason":"Core API dependency, requires >=1.0.0 since PettingZoo 1.25.0","package":"gymnasium","optional":false},{"reason":"Tutorials/integrations exist, requires >=2.0.0 since PettingZoo 1.25.0","package":"agilerl","optional":true},{"reason":"Companion library for compatibility with other ecosystems (e.g., OpenAI Gym, OpenSpiel)","package":"shimmy","optional":true},{"reason":"Companion library for common wrappers (frame stacking, observation normalization, vectorization)","package":"supersuit","optional":true}],"imports":[{"note":"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.","symbol":"Environment","correct":"from pettingzoo.butterfly import pistonball_v6\nenv = pistonball_v6.env()"},{"note":"Base environment classes for creating custom environments are located in `pettingzoo.utils.env`.","wrong":"from pettingzoo import AECEnv, ParallelEnv","symbol":"AECEnv, ParallelEnv","correct":"from pettingzoo.utils.env import AECEnv, ParallelEnv"},{"note":"Utility wrappers for input validation, stdout capture, etc., provided by PettingZoo itself. SuperSuit provides additional common preprocessing wrappers.","symbol":"wrappers","correct":"from pettingzoo.utils import wrappers"},{"note":"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()`.","wrong":"from pettingzoo.utils import AgentSelector","symbol":"AgentSelector","correct":"from pettingzoo.utils.agent_selector import AgentSelector"}],"quickstart":{"code":"from pettingzoo.butterfly import pistonball_v6\n\nenv = pistonball_v6.env(render_mode=\"human\")\nenv.reset(seed=42)\n\nfor agent in env.agent_iter():\n    observation, reward, terminated, truncated, info = env.last()\n    if terminated or truncated:\n        action = None\n    else:\n        # In a real scenario, this would be your policy's action\n        action = env.action_space(agent).sample() \n    env.step(action)\n\nenv.close()","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to a supported version (3.9, 3.10, 3.11, or 3.12).","message":"Python 3.8 is no longer supported starting from PettingZoo 1.25.0. Ensure your Python environment is 3.9 or higher.","severity":"breaking","affected_versions":">=1.25.0"},{"fix":"Update your imports to `mpe2` (e.g., `from mpe2 import simple_spread_v3`) once the `MPE2` package is stable and available.","message":"The `pettingzoo.mpe` environments are being transferred to a new dedicated `MPE2` package and will be removed from PettingZoo in a future release.","severity":"deprecated","affected_versions":">=1.25.0"},{"fix":"Replace calls to `env.seed(seed)` with `env.reset(seed=seed)`.","message":"The `env.seed()` method has been removed to align with Gymnasium API. Seeding is now handled by the `env.reset()` method.","severity":"breaking","affected_versions":">=1.23.0"},{"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)`.","message":"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.","severity":"breaking","affected_versions":">=1.23.0"},{"fix":"Update imports and references to `AgentSelector` if you are directly using this utility class.","message":"The `agent_selector` class was renamed to `AgentSelector` (capitalization change).","severity":"breaking","affected_versions":">=1.25.0"},{"fix":"Prefer Linux or macOS for development. If on Windows, be prepared to troubleshoot environment-specific dependencies (e.g., `cmake`, `swig`).","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Upgrade PettingZoo to a later stable version (e.g., `pip install pettingzoo>=1.23.0`).","message":"PettingZoo 1.22.4 was yanked from PyPI due to breaking API changes that were accidentally included. Users on this specific version should upgrade.","severity":"breaking","affected_versions":"1.22.4"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Remove the `return_info` argument from `env.reset()`. The `info` dictionary is now always returned implicitly: `observation, info = env.reset()`.","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.","error":"TypeError: reset() got an unexpected keyword argument 'return_info'"},{"fix":"Pass the `seed` argument directly to `env.reset()` instead: `env.reset(seed=123)`.","cause":"Attempting to call `env.seed()` on a PettingZoo environment in versions where this method has been deprecated and removed.","error":"AttributeError: 'PettingZooEnv' object has no attribute 'seed'"},{"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.","cause":"Using `stable_baselines3.common.env_checker.check_env` directly on a PettingZoo environment, which implements `AECEnv` or `ParallelEnv` not `gym.Env`.","error":"AssertionError: Your environment must inherit from the gym.Env class"},{"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.","cause":"The specific environment or its underlying rendering backend does not support the 'human' render_mode, or necessary display dependencies are missing.","error":"ERROR: This environment does not support render_mode='human'"},{"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').","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`.","error":"KeyError: 'agent_id' during agent interaction loop or observation/action space lookup."}]}