{"id":7915,"library":"ale-py","title":"Arcade Learning Environment (ale-py)","description":"ale-py is the Python interface to the Arcade Learning Environment (ALE), a platform for AI research built on the Atari 2600 emulator Stella. It allows researchers to develop and test AI agents for Atari games, abstracting away emulation details. The library is currently at version 0.11.2, actively maintained by the Farama Foundation, and has a steady release cadence incorporating updates like Gymnasium integration and ROM packaging.","status":"active","version":"0.11.2","language":"en","source_language":"en","source_url":"https://github.com/Farama-Foundation/Arcade-Learning-Environment","tags":["reinforcement-learning","atari","gymnasium","emulator","ai-research","game-ai"],"install":[{"cmd":"pip install ale-py","lang":"bash","label":"Basic Installation"},{"cmd":"pip install \"gymnasium[atari]\"","lang":"bash","label":"With Gymnasium and Atari ROMs"}],"dependencies":[{"reason":"Required Python version.","package":"python","optional":false},{"reason":"Required for modern OpenAI Gym API (Gymnasium) integration and Atari environments.","package":"gymnasium","optional":true}],"imports":[{"note":"The internal _ale_py module should not be directly imported.","wrong":"from ale_py._ale_py import ALEInterface","symbol":"ALEInterface","correct":"from ale_py import ALEInterface"},{"note":"While 'import ale_py.roms' works, 'from ale_py import roms' is more direct for accessing ROM paths.","wrong":"import ale_py.roms","symbol":"roms","correct":"from ale_py import roms"},{"note":"Gymnasium environments need explicit registration via `ale_py` before `gym.make` can find them.","wrong":"import gymnasium as gym\nenv = gym.make('ALE/Breakout-v5')","symbol":"register_envs (Gymnasium)","correct":"import gymnasium as gym\nimport ale_py\ngym.register_envs(ale_py)"}],"quickstart":{"code":"import gymnasium as gym\nimport ale_py\nfrom ale_py import ALEInterface, roms\n\n# --- Direct ALEInterface usage ---\nale = ALEInterface()\n# ROMs are now packaged within ale-py, access via roms.get_rom_path\nale.loadROM(roms.get_rom_path(\"breakout\"))\nale.reset_game()\nreward = ale.act(0) # Perform a 'noop' action\nscreen_obs = ale.getScreenRGB()\nprint(f\"Direct ALE: Initial reward: {reward}, Screen shape: {screen_obs.shape}\")\nale.close()\n\n# --- Gymnasium integration ---\n# Register ALE environments with Gymnasium\ngym.register_envs(ale_py)\n\nenv = gym.make('ALE/Breakout-v5', render_mode='rgb_array')\nobs, info = env.reset()\nprint(f\"Gymnasium: Initial observation shape: {obs.shape}\")\n\naction = env.action_space.sample() # Take a random action\nobs, reward, terminated, truncated, info = env.step(action)\nprint(f\"Gymnasium: Step reward: {reward}, Terminated: {terminated}, Truncated: {truncated}\")\n\nenv.close()\n","lang":"python","description":"This quickstart demonstrates both the direct Python interface of ALEInterface to interact with Atari games and its integration with the Gymnasium API. It shows how to load a ROM (now included in the package), reset the game, take an action, and retrieve observations. The Gymnasium example highlights environment registration and interaction."},"warnings":[{"fix":"Migrate your environment interaction code to use Gymnasium's API. Ensure `gymnasium` is installed (`pip install gymnasium`). Explicitly import `ale_py` and call `gymnasium.register_envs(ale_py)` before creating any Atari environments with `gymnasium.make`.","message":"Starting with ale-py v0.9.0, the library transitioned from supporting OpenAI Gym to Gymnasium (>= 1.0.0a1). The `gym` package is no longer maintained, and `ale-py` uses Gymnasium as the sole backend environment. This requires adapting code that used the older `gym` API.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"For packaged ROMs, use `from ale_py import roms; ale.loadROM(roms.get_rom_path(\"gamename\"))`. If you need custom ROMs, continue using `ale-import-roms /path/to/roms/` or set the `ALE_ROM_DIR` environment variable to your ROM directory.","message":"Atari ROMs are now packaged directly within the `ale-py` PyPI installation since v0.9.0, eliminating the need for `pip install \"gym[accept-rom-license]\"` or the `ale-import-roms` tool for standard ROMs. However, custom or additional ROMs can still be managed via `ale-import-roms` or by setting the `ALE_ROM_DIR` environment variable.","severity":"breaking","affected_versions":">=0.9.0"},{"fix":"Rely on the ROMs packaged within `ale-py` via `roms.get_rom_path()` or use the `ale-import-roms` command-line tool/`ALE_ROM_DIR` environment variable for managing custom ROMs. The `roms` module itself is still correct for accessing *internal* ROM paths.","message":"Direct importing of `atari-py roms` (e.g., `import ale_py.roms as roms` to get external ROMs) will not be supported in future releases of `ale-py` for external ROM handling.","severity":"deprecated","affected_versions":">=0.9.0"},{"fix":"Ensure you are using `ale-py` version 0.9.0 or newer for Python 3.12+ compatibility, or use an earlier Python version (e.g., 3.11) with older `ale-py` versions. Always ensure `pip` is up-to-date (`pip install --upgrade pip`).","message":"Older versions of `ale-py` might not have wheels available for the latest Python versions (e.g., Python 3.12 prior to `ale-py` v0.9.0). This can lead to installation failures.","severity":"gotcha","affected_versions":"<0.9.0 with Python >=3.12"},{"fix":"Initialize your Gymnasium environment with `render_mode='human'` or `render_mode='rgb_array'` (e.g., `env = gym.make('ALE/Breakout-v5', render_mode='rgb_array')`).","message":"When using Gymnasium environments, the `env.render()` method is generally discouraged in favor of supplying the `render_mode` keyword argument during environment initialization for improved rendering capabilities (frame-perfect, audio, scaling).","severity":"gotcha","affected_versions":"All versions with Gymnasium"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `ale-py` is installed correctly, possibly in a fresh virtual environment. For Gymnasium, you *must* explicitly `import ale_py` and then call `gymnasium.register_envs(ale_py)` before creating any Atari environments with `gym.make()`.","cause":"This often occurs when `ale-py`'s internal C++ bindings are not correctly compiled or located, or when Gymnasium environments are used without properly registering `ale_py`.","error":"No module named 'ale_py._ale_py' (or similar ModuleNotFoundError when importing gym)"},{"fix":"Upgrade `pip` (`pip install --upgrade pip`). If the error persists, check `ale-py`'s PyPI page for supported Python versions and consider using a compatible Python version (e.g., Python 3.9-3.11 for older `ale-py`, or `ale-py` >=0.9.0 for Python 3.12+).","cause":"This error typically indicates that your Python version is not supported by the available `ale-py` wheels on PyPI, or your `pip` is outdated.","error":"ERROR: Could not find a version that satisfies the requirement ale-py (from versions: none) / ERROR: No matching distribution found for ale-py"},{"fix":"Ensure you are using `gymnasium` and `ale-py >=0.9.0`. Explicitly import `ale_py` and then call `gymnasium.register_envs(ale_py)` *before* `gym.make()`. If using `pip install \"gymnasium[atari]\"`, ROMs should be automatically handled. If you need custom ROMs, use `ale-import-roms /path/to/roms` or set `ALE_ROM_DIR`.","cause":"Older `gym` versions required manual ROM installation or `gym[atari,accept-rom-license]`. With Gymnasium, the environment registration is often missed, or a very old `ale-py` is used that doesn't include ROMs.","error":"game_env = gym.make('Pong-v4') fails with a ROM error or environment not found"}]}