pettingzoo

What it is and what it does

PettingZoo is a multi-agent reinforcement learning library that extends Gymnasium's single-agent paradigm to support environments where multiple agents interact simultaneously or sequentially. It models environments as Agent Environment Cycle (AEC) games to provide a unified API for diverse multi-agent scenarios—from competitive Atari games to cooperative puzzle tasks—while maintaining strict environment versioning for reproducibility.

The library offers two interaction modes: a sequential AEC API where agents take turns, and a parallel API for simultaneous action environments. It depends on numpy for numerical operations, gymnasium for the base environment interface, and typing-extensions for type hints. The core install is lightweight, with optional extras for specific environment families that may have system-level dependencies.

Use it for:

• Train cooperative multi-agent policies in environments like Pistonball where agents must coordinate to solve tasks.
• Benchmark competitive multi-agent algorithms on classic games (Tic-Tac-Toe, Connect Four) and Atari titles.
• Implement curriculum learning and self-play training using PettingZoo's environment versioning for reproducible experiments.
• Research agent communication and emergent behavior in mixed-sum games combining cooperation and competition.
• Prototype custom multi-agent environments using PettingZoo's API and environment creation tutorials.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

PettingZoo provides multi-agent reinforcement learning environments with a Gymnasium-like API, supporting both sequential (AEC) and parallel action modes across Atari, classic games, and custom environments.

Yes. PettingZoo is actively maintained, has low install friction, carries a permissive MIT license, and is the standard library for multi-agent RL research. It has no known vulnerabilities, supports current Python versions (3.10–3.14), and integrates cleanly with popular RL training frameworks. Install it if you need a multi-agent environment interface; use base install for API exploration and add extras only for specific environment families.

Install

pettingzoo on PyPI

pip install pettingzoo

uv add pettingzoo

poetry add pettingzoo

Installing pettingzoo

Before you install

Low install friction with a pure-wheel distribution and minimal core dependencies (numpy, gymnasium, typing-extensions). Active maintenance with a release 1 day old and 3489 repository stars. Supports Python 3.10 through 3.14. Optional extras for specific environment families (atari, all) available for selective installation.

License in practice

MIT License (permissive) allows commercial and private use with minimal restrictions, making it suitable for research, commercial deployment, and derivative work.

Quickstart

pip install pettingzoo

from pettingzoo import make
env = make("aec", "butterfly/pistonball-v6")
env.reset()
for agent in env.agent_iter():
    observation, reward, termination, truncation, info = env.last()
    action = None if termination or truncation else env.action_space(agent).sample()
    env.step(action)

Optional environment families (Atari, Butterfly, etc.) require additional dependencies installable via extras like 'pettingzoo[atari]' or 'pettingzoo[all]'; base install provides core API only.

Verify before relying

• Whether specific environment families (Atari, Butterfly, Classic, SISL) are included in the base install or require extras.
• Performance characteristics and scalability limits for large numbers of agents.
• Compatibility with specific RL training frameworks beyond the mentioned examples (CleanRL, Tianshou, AgileRL).

Package facts

Evidence: pettingzoo-1.27.0-py3-none-any.whl

Keywords: Reinforcement Learning, game, RL, AI, gymnasium

Tags

More Artificial Intelligence packages

Further reading