Install & Compatibility
Where this runs
tested against v2.0.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.11
8/16 runs
13/16 runs
py 3.13
8/16 runs
8/16 runs
92MB installed
● package 92MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DmControlCompatibilityV0
✓ from shimmy import DmControlCompatibilityV0
✗ from shimmy.dm_control_compatibility import DmControlCompatibilityV0
This quickstart demonstrates how to wrap a single-agent DeepMind Control environment for Gymnasium and a multi-agent DeepMind Control Soccer environment for PettingZoo using Shimmy. Note the explicit `import shimmy` which became necessary with Gymnasium 1.0.0a1. [8, 9, 15]
import gymnasium as gym
import shimmy # This import is now necessary for environment registration in Gymnasium v1.0+
# Example for a single-agent DeepMind Control environment
env = gym.make("dm_control/acrobot-swingup_sparse-v0", render_mode="human")
observation, info = env.reset(seed=42)
for _ in range(100):
action = env.action_space.sample()
observation, reward, terminated, truncated, info = env.step(action)
if terminated or truncated:
observation, info = env.reset()
env.close()
# Example for a multi-agent DeepMind Control Soccer environment (PettingZoo API)
from shimmy.dm_control_multiagent_compatibility import DmControlMultiAgentCompatibilityV0
from dm_control.locomotion import soccer as dm_soccer
multi_agent_env = dm_soccer.load(team_size=2)
multi_agent_env = DmControlMultiAgentCompatibilityV0(multi_agent_env, render_mode="human")
observations, infos = multi_agent_env.reset()
while multi_agent_env.agents:
actions = {agent: multi_agent_env.action_space(agent).sample() for agent in multi_agent_env.agents}
observations, rewards, terminations, truncations, infos = multi_agent_env.step(actions)
multi_agent_env.close()
Debug
Known issues
breakingWith Shimmy v2.0.0 and Gymnasium >= 1.0.0a1, explicit `import shimmy` is required for environment registration. Previously, modules could configure themselves to be loaded on `import gymnasium`, which is no longer supported.fixEnsure `import shimmy` is present in your code before calling `gymnasium.make()` for Shimmy-wrapped environments. [8]
affects: >=2.0.0
breakingShimmy v2.0.0 removed the direct Atari wrapper. `ale-py` now natively supports Gymnasium, making the Shimmy wrapper redundant. If you were using `shimmy.atari_compatibility.AtariCompatibilityV0`, you should now use `ale_py`'s native Gymnasium integration.fixRemove `shimmy.atari_compatibility` imports and use `ale-py` directly, ensuring `ale-py` is installed with Gymnasium support. [8]
affects: >=2.0.0
breakingPython 3.7 support was dropped in Shimmy v1.2.0. The library now requires Python 3.10 or newer.fixUpgrade your Python installation to version 3.10 or higher. [8, 16]
affects: >=1.2.0
breakingThe `install_melting_pot.sh` script was removed in Shimmy v1.3.0 as the Melting Pot wrapper now uses the `dm-meltingpot` PyPI release, simplifying installation.fixInstall `shimmy[meltingpot]` and ensure `dm-meltingpot` is correctly installed via pip, rather than relying on the old script. [8]
affects: >=1.3.0
gotchaDeepMind Melting Pot environments require Python version >= 3.10.fixEnsure your Python environment is 3.10 or newer if you intend to use the Melting Pot wrapper. [8]
affects: All versions supporting Melting Pot
gotchaSpecific environment dependencies must be installed via Shimmy's extras, e.g., `pip install shimmy[dm-control]` for DeepMind Control or `pip install shimmy[openspiel]` for OpenSpiel. Failing to do so will result in `ModuleNotFoundError` when trying to use those wrappers or environments.fixInstall Shimmy with the appropriate extra dependencies for the environments you plan to use. Refer to the official documentation for a list of available extras. [12]
affects: All versions
gotchaSeeding for the `DmControlMultiAgentCompatibilityV0` environment (e.g., DeepMind Soccer) is noted as non-deterministic due to the underlying environment's setup.fixBe aware that results may not be perfectly reproducible even with a fixed seed when using `DmControlMultiAgentCompatibilityV0`. [2]
affects: All versions
Upgrade
Version history
2.0.1latest on PyPI · released Apr 10, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
gymnasiumoptionalCore dependency for single-agent environment compatibility. Required for most wrappers.
pettingzoooptionalCore dependency for multi-agent environment compatibility. Required for multi-agent wrappers.
dm_controloptionalRequired for DeepMind Control wrappers.
dm_meltingpotoptionalRequired for DeepMind Melting Pot wrappers.
ale-pyoptionalRequired for Atari environments. Shimmy v2.0.0+ no longer wraps Atari directly as ale-py now supports Gymnasium natively.