{"id":7712,"library":"shimmy","title":"Shimmy","description":"Shimmy is an API conversion tool that provides Gymnasium and PettingZoo bindings for popular external reinforcement learning environments. It allows users to access a wide range of single and multi-agent environments under a single standard API. The current version is 2.0.1, with releases occurring a few times a year to ensure compatibility with new versions of Gymnasium and PettingZoo, as well as to add support for new external environments.","status":"active","version":"2.0.1","language":"en","source_language":"en","source_url":"https://github.com/Farama-Foundation/Shimmy","tags":["reinforcement-learning","gymnasium","pettingzoo","environment-wrappers","api-conversion","deepmind-control","melting-pot","openspiel"],"install":[{"cmd":"pip install shimmy","lang":"bash","label":"Base installation"},{"cmd":"pip install shimmy[dm-control]","lang":"bash","label":"DeepMind Control Suite environments"},{"cmd":"pip install shimmy[meltingpot]","lang":"bash","label":"DeepMind Melting Pot environments"},{"cmd":"pip install shimmy[all]","lang":"bash","label":"All supported environments"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false},{"reason":"Core dependency for single-agent environment compatibility. Required for most wrappers.","package":"gymnasium","optional":true},{"reason":"Core dependency for multi-agent environment compatibility. Required for multi-agent wrappers.","package":"pettingzoo","optional":true},{"reason":"Required for DeepMind Control wrappers.","package":"dm_control","optional":true},{"reason":"Required for DeepMind Melting Pot wrappers.","package":"dm_meltingpot","optional":true},{"reason":"Required for Atari environments. Shimmy v2.0.0+ no longer wraps Atari directly as ale-py now supports Gymnasium natively.","package":"ale-py","optional":true}],"imports":[{"symbol":"DmControlCompatibilityV0","correct":"from shimmy.dm_control_compatibility import DmControlCompatibilityV0"},{"symbol":"DmControlMultiAgentCompatibilityV0","correct":"from shimmy.dm_control_multiagent_compatibility import DmControlMultiAgentCompatibilityV0"},{"symbol":"OpenSpielCompatibilityV0","correct":"from shimmy.openspiel_compatibility import OpenSpielCompatibilityV0"},{"symbol":"MeltingPotCompatibilityV0","correct":"from shimmy.meltingpot_compatibility import MeltingPotCompatibilityV0"},{"symbol":"GymV26CompatibilityV0","correct":"from shimmy.openai_gym_compatibility import GymV26CompatibilityV0"}],"quickstart":{"code":"import gymnasium as gym\nimport shimmy # This import is now necessary for environment registration in Gymnasium v1.0+\n\n# Example for a single-agent DeepMind Control environment\nenv = gym.make(\"dm_control/acrobot-swingup_sparse-v0\", render_mode=\"human\")\n\nobservation, info = env.reset(seed=42)\nfor _ in range(100):\n    action = env.action_space.sample()\n    observation, reward, terminated, truncated, info = env.step(action)\n    if terminated or truncated:\n        observation, info = env.reset()\nenv.close()\n\n# Example for a multi-agent DeepMind Control Soccer environment (PettingZoo API)\nfrom shimmy.dm_control_multiagent_compatibility import DmControlMultiAgentCompatibilityV0\nfrom dm_control.locomotion import soccer as dm_soccer\n\nmulti_agent_env = dm_soccer.load(team_size=2)\nmulti_agent_env = DmControlMultiAgentCompatibilityV0(multi_agent_env, render_mode=\"human\")\n\nobservations, infos = multi_agent_env.reset()\nwhile multi_agent_env.agents:\n    actions = {agent: multi_agent_env.action_space(agent).sample() for agent in multi_agent_env.agents}\n    observations, rewards, terminations, truncations, infos = multi_agent_env.step(actions)\nmulti_agent_env.close()","lang":"python","description":"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]"},"warnings":[{"fix":"Ensure `import shimmy` is present in your code before calling `gymnasium.make()` for Shimmy-wrapped environments. [8]","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Remove `shimmy.atari_compatibility` imports and use `ale-py` directly, ensuring `ale-py` is installed with Gymnasium support. [8]","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Python installation to version 3.10 or higher. [8, 16]","message":"Python 3.7 support was dropped in Shimmy v1.2.0. The library now requires Python 3.10 or newer.","severity":"breaking","affected_versions":">=1.2.0"},{"fix":"Install `shimmy[meltingpot]` and ensure `dm-meltingpot` is correctly installed via pip, rather than relying on the old script. [8]","message":"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.","severity":"breaking","affected_versions":">=1.3.0"},{"fix":"Ensure your Python environment is 3.10 or newer if you intend to use the Melting Pot wrapper. [8]","message":"DeepMind Melting Pot environments require Python version >= 3.10.","severity":"gotcha","affected_versions":"All versions supporting Melting Pot"},{"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]","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware that results may not be perfectly reproducible even with a fixed seed when using `DmControlMultiAgentCompatibilityV0`. [2]","message":"Seeding for the `DmControlMultiAgentCompatibilityV0` environment (e.g., DeepMind Soccer) is noted as non-deterministic due to the underlying environment's setup.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add `import shimmy` at the top of your script. This registers the environments with Gymnasium. [8]","cause":"After upgrading Shimmy to v2.0.0+ and Gymnasium to v1.0.0a1+, the explicit `import shimmy` statement is missing, preventing environment registration.","error":"AttributeError: module 'gymnasium' has no attribute 'make'"},{"fix":"Install Shimmy with the `dm-control` extra: `pip install shimmy[dm-control]`. [12]","cause":"Attempting to use a Shimmy wrapper for DeepMind Control environments without installing the necessary `dm-control` dependency via Shimmy's extras.","error":"ModuleNotFoundError: No module named 'dm_control'"},{"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]","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.","error":"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."},{"fix":"Access the action mask from the `info` dictionary, e.g., `action_mask = info[\"action_mask\"]`. [7]","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.","error":"TypeError: 'NoneType' object is not callable (or similar error related to action masks for OpenSpiel)"}]}