最完整Gymnasium安装指南：从PyPI到源码编译的全流程

最完整Gymnasium安装指南：从PyPI到源码编译的全流程

【免费下载链接】Gymnasium An API standard for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym) 项目地址: https://gitcode.com/GitHub_Trending/gy/Gymnasium

读完你将获得

• 3种安装方式的详细对比与操作指南
• 解决95%安装问题的故障排除方案
• 环境验证与基础使用的标准化流程
• 分场景的依赖管理最佳实践

为什么选择Gymnasium？

你还在为OpenAI Gym的维护停滞而困扰吗？作为Gym的官方继任者，Gymnasium不仅继承了原项目的全部功能，还带来了持续的维护支持、API改进和新特性开发。无论是学术研究、算法开发还是教学演示，Gymnasium都提供了标准化的强化学习环境接口，让你的RL算法轻松对接Atari游戏、物理模拟等100+种环境。

安装方式对比

安装方式	命令	优点	缺点	适用场景
PyPI基础安装	pip install gymnasium	最快、最简单	仅包含核心功能	快速体验、CI环境
PyPI完整安装	pip install "gymnasium[all]"	一键获取所有环境	下载量大(>500MB)	本地开发、完整功能测试
源码编译安装	多步骤编译	可修改源码、最新特性	耗时较长、需编译工具	贡献者、高级定制

1. PyPI基础安装（推荐新手）

1.1 系统要求

• Python版本：3.10-3.13（官方支持版本）
• 操作系统：Linux/macOS（Windows需WSL2或手动适配）
• 基础依赖：pip >= 20.0.2, setuptools >= 41.2.0

1.2 安装命令

# 更新pip到最新版本
pip install --upgrade pip

# 基础安装（仅包含核心API和部分环境）
pip install gymnasium

1.3 验证安装

import gymnasium as gym
env = gym.make("CartPole-v1")
observation, info = env.reset()
print(f"观测空间: {env.observation_space}")  # 应输出Box(4,)
print(f"动作空间: {env.action_space}")      # 应输出Discrete(2)
env.close()

2. 分场景依赖安装

2.1 按环境家族安装

环境家族	安装命令	典型环境	依赖大小
经典控制环境	pip install "gymnasium[classic_control]"	CartPole, MountainCar	~2MB
2D物理环境	pip install "gymnasium[box2d]"	LunarLander, BipedalWalker	~40MB
Atari游戏	pip install "gymnasium[atari]"	Breakout, SpaceInvaders	~200MB
MuJoCo物理	pip install "gymnasium[mujoco]"	Humanoid, Ant	~80MB

2.2 专业功能安装

# 视频录制功能
pip install "gymnasium[recording]"

# 并行环境功能
pip install "gymnasium[vector]"

# 开发文档工具
pip install "gymnasium[docs]"

3. 源码编译安装（适合开发者）

3.1 准备工作

# 安装编译依赖
sudo apt-get update && sudo apt-get install -y \
    git \
    build-essential \
    libgl1-mesa-dev \
    libglib2.0-0

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/gy/Gymnasium.git
cd Gymnasium

3.2 编译与安装

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate  # Windows

# 安装构建依赖
pip install -e .[dev]

# 验证安装
pip list | grep gymnasium  # 应显示 editable 标记

3.3 参与开发

# 安装预提交钩子
pre-commit install

# 运行测试套件
pytest tests/ -n auto

4. 常见问题解决方案

4.1 环境依赖冲突

# 问题：mujoco-py与其他库冲突
# 解决：创建专用虚拟环境
python -m venv gym-venv
source gym-venv/bin/activate
pip install "gymnasium[mujoco]"

4.2 Atari环境启动失败

# 问题：No module named 'ale_py'
# 解决：单独安装Atari依赖
pip install ale-py==0.8.1

4.3 图形界面无法显示

# 问题：render_mode="human"无窗口显示
# 解决：安装系统图形依赖
sudo apt-get install -y libsdl2-dev pygame

5. 环境验证与基础使用

5.1 标准验证流程

import gymnasium as gym
import numpy as np

# 测试经典控制环境
def test_cartpole():
    env = gym.make("CartPole-v1", 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()

# 测试Atari环境（需安装[atari]依赖）
def test_atari():
    env = gym.make("ALE/Breakout-v5", render_mode="human")
    observation, info = env.reset()
    for _ in range(200):
        action = env.action_space.sample()
        observation, reward, terminated, truncated, info = env.step(action)
        if terminated or truncated:
            observation, info = env.reset()
    env.close()

# 运行验证
test_cartpole()
test_atari()  # 仅在安装Atari依赖后执行

5.2 性能基准测试

import time

def benchmark_env(env_name, steps=10000):
    env = gym.make(env_name)
    start_time = time.time()
    
    observation, info = env.reset()
    for _ in range(steps):
        action = env.action_space.sample()
        observation, reward, terminated, truncated, info = env.step(action)
        if terminated or truncated:
            observation, info = env.reset()
    
    duration = time.time() - start_time
    print(f"{env_name}: {steps/duration:.2f} FPS")
    env.close()

# 测试性能
benchmark_env("CartPole-v1")  # 应达到>1000 FPS
benchmark_env("LunarLander-v2")  # 应达到>500 FPS

6. 依赖管理最佳实践

6.1 生产环境依赖锁定

# 导出当前环境依赖
pip freeze > requirements.txt

# 在新环境中复现
pip install -r requirements.txt

6.2 分场景依赖文件示例

# requirements-basic.txt
gymnasium>=0.29.0

# requirements-research.txt
gymnasium[all]==0.29.1
stable-baselines3==2.0.0
tensorboard==2.14.0

7. 总结与后续学习路径

恭喜！你已成功安装并配置了Gymnasium环境。接下来推荐：

1. 基础教程：gymnasium make CartPole-v1 体验经典控制问题
2. 进阶功能：学习向量环境(VectorEnv)提升训练效率
3. 环境开发：参考gymnasium/envs目录开发自定义环境
4. 算法实现：结合Stable-Baselines3等库实现强化学习算法

【免费下载链接】Gymnasium An API standard for single-agent reinforcement learning environments, with popular reference environments and related utilities (formerly Gym) 项目地址: https://gitcode.com/GitHub_Trending/gy/Gymnasium