---
id: pettingzoo
version: "1.27.0"
license: MIT License
license_treatment: permissive
maintenance: active
---

# pettingzoo — Gymnasium for multi-agent reinforcement learning.

License: permissive · Maintenance: active · Downloads: 311.6K/mo

## 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 above — 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

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

- License: MIT License (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 311.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

multi-agent reinforcement learning, MARL environments, multi-agent RL library, cooperative game environments, multi-agent gymnasium, agent environment cycle, parallel multi-agent training, multi-agent-rl, game-environments, research-framework

[View on SkillFed](https://skillfed.io/packages/pettingzoo) · [View on PyPI](https://pypi.org/project/pettingzoo/)