Shimmy

Common errors

• AttributeError: module 'gymnasium' has no attribute 'make'

  cause After upgrading Shimmy to v2.0.0+ and Gymnasium to v1.0.0a1+, the explicit `import shimmy` statement is missing, preventing environment registration.
  fix Add `import shimmy` at the top of your script. This registers the environments with Gymnasium. [8]

• ModuleNotFoundError: No module named 'dm_control'

  cause Attempting to use a Shimmy wrapper for DeepMind Control environments without installing the necessary `dm-control` dependency via Shimmy's extras.
  fix Install Shimmy with the `dm-control` extra: `pip install shimmy[dm-control]`. [12]

• ValueError: Use the env argument to wrap an existing environment. All other arguments [...] are specific to DM Lab and will be used to load a new environment.

  cause When using `DmControlMultiAgentCompatibilityV0` (or similar wrappers) to wrap an already loaded environment (e.g., `DmControlMultiAgentCompatibilityV0(env=my_dm_soccer_env)`), environment creation arguments like `team_size` are also provided.
  fix When wrapping an *existing* environment, only pass the `env` argument and optionally `render_mode`. Do not pass arguments like `team_size`, `time_limit`, etc., which are for *creating* a new environment. [2]

• TypeError: 'NoneType' object is not callable (or similar error related to action masks for OpenSpiel)

  cause For Shimmy's OpenSpiel environments, action masks are typically stored in the `info` dictionary from `env.last()` or `env.step()`, not directly in the observation dictionary, which might be a common pattern for other PettingZoo environments.
  fix Access the action mask from the `info` dictionary, e.g., `action_mask = info["action_mask"]`. [7]

Warnings

• breaking With 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.
  Fix: Ensure `import shimmy` is present in your code before calling `gymnasium.make()` for Shimmy-wrapped environments. [8]
• breaking Shimmy 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.
  Fix: Remove `shimmy.atari_compatibility` imports and use `ale-py` directly, ensuring `ale-py` is installed with Gymnasium support. [8]
• breaking Python 3.7 support was dropped in Shimmy v1.2.0. The library now requires Python 3.10 or newer.
  Fix: Upgrade your Python installation to version 3.10 or higher. [8, 16]
• breaking The `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.
  Fix: Install `shimmy[meltingpot]` and ensure `dm-meltingpot` is correctly installed via pip, rather than relying on the old script. [8]
• gotcha DeepMind Melting Pot environments require Python version >= 3.10.
  Fix: Ensure your Python environment is 3.10 or newer if you intend to use the Melting Pot wrapper. [8]
• gotcha Specific 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.
  Fix: Install 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]
• gotcha Seeding for the `DmControlMultiAgentCompatibilityV0` environment (e.g., DeepMind Soccer) is noted as non-deterministic due to the underlying environment's setup.
  Fix: Be aware that results may not be perfectly reproducible even with a fixed seed when using `DmControlMultiAgentCompatibilityV0`. [2]

Install

• pip install shimmy Base installation
• pip install shimmy[dm-control] DeepMind Control Suite environments
• pip install shimmy[meltingpot] DeepMind Melting Pot environments
• pip install shimmy[all] All supported environments

Imports

• DmControlCompatibilityV0

  from shimmy.dm_control_compatibility import DmControlCompatibilityV0

• DmControlMultiAgentCompatibilityV0

  from shimmy.dm_control_multiagent_compatibility import DmControlMultiAgentCompatibilityV0

• OpenSpielCompatibilityV0

  from shimmy.openspiel_compatibility import OpenSpielCompatibilityV0

• MeltingPotCompatibilityV0

  from shimmy.meltingpot_compatibility import MeltingPotCompatibilityV0

• GymV26CompatibilityV0

  from shimmy.openai_gym_compatibility import GymV26CompatibilityV0

Quickstart

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()