Arcade Learning Environment (ale-py)

Common errors

• No module named 'ale_py._ale_py' (or similar ModuleNotFoundError when importing gym)

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

• ERROR: Could not find a version that satisfies the requirement ale-py (from versions: none) / ERROR: No matching distribution found for ale-py

  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.
  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+).

• game_env = gym.make('Pong-v4') fails with a ROM error or environment not found

  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.
  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`.

Warnings

• breaking 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.
  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`.
• breaking 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.
  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.
• deprecated 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.
  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.
• gotcha 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.
  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`).
• gotcha 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).
  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')`).

Install

• pip install ale-py Basic Installation
• pip install "gymnasium[atari]" With Gymnasium and Atari ROMs

Imports

• ALEInterface
  wrong:

  from ale_py._ale_py import ALEInterface

  correct:

  from ale_py import ALEInterface

  The internal _ale_py module should not be directly imported.
• roms
  wrong:

  import ale_py.roms

  correct:

  from ale_py import roms

  While 'import ale_py.roms' works, 'from ale_py import roms' is more direct for accessing ROM paths.
• register_envs (Gymnasium)
  wrong:

  import gymnasium as gym
  env = gym.make('ALE/Breakout-v5')

  correct:

  import gymnasium as gym
  import ale_py
  gym.register_envs(ale_py)

  Gymnasium environments need explicit registration via `ale_py` before `gym.make` can find them.

Quickstart

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.

import gymnasium as gym
import ale_py
from ale_py import ALEInterface, roms

# --- Direct ALEInterface usage ---
ale = ALEInterface()
# ROMs are now packaged within ale-py, access via roms.get_rom_path
ale.loadROM(roms.get_rom_path("breakout"))
ale.reset_game()
reward = ale.act(0) # Perform a 'noop' action
screen_obs = ale.getScreenRGB()
print(f"Direct ALE: Initial reward: {reward}, Screen shape: {screen_obs.shape}")
ale.close()

# --- Gymnasium integration ---
# Register ALE environments with Gymnasium
gym.register_envs(ale_py)

env = gym.make('ALE/Breakout-v5', render_mode='rgb_array')
obs, info = env.reset()
print(f"Gymnasium: Initial observation shape: {obs.shape}")

action = env.action_space.sample() # Take a random action
obs, reward, terminated, truncated, info = env.step(action)
print(f"Gymnasium: Step reward: {reward}, Terminated: {terminated}, Truncated: {truncated}")

env.close()