# Migrate a Custom Environment From OpenAI Gym to Gymnasium

Yes. An agent ports a custom Gym environment to the Gymnasium API, splits done into terminated and truncated, checks seeded rollouts, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-gym-to-gymnasium/gym/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

Gym is no longer developed and Gymnasium is its maintained continuation, but the move is an API migration, not a rename: `reset` takes a seed and returns two values, `step` returns five, seeding and rendering moved, and environments made with `gymnasium.make` are wrapped in checkers that enforce all of it. The agent first reads what the environment actually implements. In a package like hardmaru/slimevolleygym, whose README says the examples target Gym 0.19.0 or earlier because later versions break the API, everything is in `slimevolleygym/slimevolley.py`: a `SlimeVolleyEnv(gym.Env)` with a `seed()` method, a `reset()` with no parameters, a `step()` that returns `obs, reward, done, info`, a `metadata` dict keyed `render.modes` and `video.frames_per_second`, two bundled wrappers, and four `register()` calls.

Changing the four imports to `gymnasium` is enough for `gym.make("SlimeVolley-v0")` to return an environment, and that is where the real list begins. Gymnasium warns that the metadata has no `render_modes`. `env.reset(seed=1)` raises `TypeError: SlimeVolleyEnv.reset() got an unexpected keyword argument 'seed'`. `env.step(action)` raises `ValueError: not enough values to unpack (expected 5, got 4)`. `env.seed(3)` fails because the wrapper has no such attribute. The agent fixes each in the environment: `reset(self, *, seed=None, options=None)` calls `super().reset(seed=seed)`, rebuilds the game from `self.np_random` as the old `seed()` did, and returns `obs, info`; the metadata keys become `render_modes` and `render_fps`.

Splitting `done` takes reading the code, not pattern matching. This `step()` sets `done` in two places: when `self.t >= self.t_limit`, which is a time limit and becomes `truncated`, and when either agent's life count reaches zero, which is the game ending and becomes `terminated`. Getting these backwards changes how value-based learners bootstrap, with no error anywhere. The bundled `FrameStack` wrapper and the evaluation loop at the bottom of the file unpack four values and are updated the same way.

Two parts need judgment and the agent reports them as such. The package documents a two-player call, `env.step(action1, action2)`, and through Gymnasium's wrappers that raises `TypeError: OrderEnforcing.step() takes 2 positional arguments but 3 were given`; the environment already has an `otherAction` attribute for passing the second action through wrappers, so the agent documents that route and `env.unwrapped.step`. Human-mode drawing imports `gym.envs.classic_control.rendering`, which Gymnasium does not ship; pixel observations are drawn with OpenCV into arrays and keep working, and the agent leaves the windowed viewer behind a clear error unless asked to port it. It also notes that installing Gymnasium brings NumPy 2, where the `np.product` calls in `slimevolleygym/mlp.py` no longer exist, and replaces them with `np.prod`.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Port this project's custom environments from OpenAI Gym to Gymnasium. Read every class that subclasses gym.Env or a gym wrapper and list what each implements: seed, reset, step, render, close, metadata, spaces, and every register() call. Replace gym imports with gymnasium and the gym requirement in every manifest. Update reset to accept seed and options, call super().reset(seed=seed), use self.np_random for all randomness, and return (observation, info). Update step to return (observation, reward, terminated, truncated, info): read each place the old done flag is set and classify it as a true end of episode (terminated) or a time or step limit (truncated), and list each classification with its line. Rename metadata keys to render_modes and render_fps, accept render_mode in the constructor, and make render() take no mode argument. Fix the bundled wrappers and every loop in the repository that calls reset or step. If any code depends on gym modules Gymnasium does not have (for example classic_control.rendering) or calls step with extra arguments, do not guess: keep headless rendering working, and report what was left unported and why. Make observation dtypes match the declared observation space. Then verify: run gymnasium.utils.env_checker.check_env on each registered id, and run two rollouts of 500 steps with the same seed and the same action sequence and confirm the observations and rewards are identical, and one with a different seed that differs. Do not retrain or evaluate models. Open a pull request with the classifications, the checker output and the list of anything unported.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request centred on one file. For slimevolleygym the diff changes `slimevolley.py`, the two `np.product` lines in `mlp.py`, the `gym` entries in `setup.py` and `requirements.txt`, and the usage examples in the README. The description gives a table of every place `done` was set, with the line, the condition, and whether it became `terminated` or `truncated`, because that is the decision a reviewer most needs to check.

Below it are the outputs: `check_env` for each of the four registered ids, and the seeded-rollout comparison showing the same seed reproduces the same episode. Warnings the checker still prints are quoted, not hidden; in this package the state observations are float64 while the checker expects float32 for the declared space, and the agent either casts them or explains why it left them.

The last section lists what was not ported: the windowed viewer, and the training and evaluation scripts that import stable-baselines 2, which targets the old Gym API and is outside this change. The reviewer decides whether those scripts move to a library that supports Gymnasium in a later pull request.

## Run it on every Linear issue labelled gymnasium

Research groups tend to have many small environment packages, each ported when someone next needs it. Connect Linear under Settings → Connections, then add an automation to the Project that holds the repository with a `linear` trigger on `linear.issue.labeled` and the label `gymnasium`, and save the prompt above. The run starts when someone in your Rush org applies the label. The issue is added after the prompt as event text, so it is the place for facts the prompt cannot know, such as which registered id your experiments use or whether a time limit should count as truncation.

The trigger needs a Linear connection for the member the automation runs as, and a label applied by an app integration does not fire it.

## Why run it on Rush?

The failure mode of this migration is an environment that runs and is subtly wrong: a time limit reported as termination, or a `reset` that ignores its seed so every experiment draws different episodes. Neither raises an error. Both are caught by checks that are cheap to describe and tedious to do by hand, the environment checker and a pair of seeded rollouts compared value by value. The agent runs them in its sandbox and the commands and their output are kept in the session transcript, so the pull request's claim of reproducibility can be opened and read.

The sandbox also gives the port a clean install. Old Gym pins are hard to keep alive next to current NumPy, and a developer's working environment for a legacy package usually has years of drift in it. Starting empty with current Gymnasium shows what a new user of the package will meet, including side effects of the upgrade such as NumPy 2.

## Frequently asked questions

### Can I just write import gymnasium as gym?

That gets you past the import and no further. `gymnasium.make` wraps the environment in checkers that call `reset(seed=...)` and expect five values from `step`, so an environment written for the old API fails on the first call. The class itself has to change.

### How do I decide between terminated and truncated?

`terminated` means the task reached an end state defined by the environment, such as a win, a loss or a crash. `truncated` means the episode was cut off from outside, usually by a step limit. Learning algorithms treat the two differently when estimating future reward, so each place the old code set `done` has to be read and classified.

### What happened to env.seed()?

It was removed. Pass the seed to `reset(seed=...)`, call `super().reset(seed=seed)` inside your environment, and draw random numbers from `self.np_random`. Code that built its own generator in `seed()` needs that logic moved into `reset`.

### Will my trained models still work?

The observation and action spaces do not change in a faithful port, so saved policies see the same inputs. The library that loads them is a separate question: a model saved by a framework built on the old Gym API needs that framework, or a conversion, to run. The agent ports the environment and reports which scripts depend on such a framework.

### Does rendering still work on a headless machine?

Array rendering does. Gymnasium takes `render_mode="rgb_array"` at construction and `render()` returns the frame. Window rendering that relied on Gym's old pyglet-based `rendering` module has to be rewritten, since that module is not part of Gymnasium.

## More jobs like this: Upgrade dependencies weekly

- [Migrate From the Deprecated @hapi/joi Package to joi](https://getrush.ai/run/migrate-hapi-joi-to-joi/hapi-joi/)
- [Migrate an Express App From Jade to Pug](https://getrush.ai/run/migrate-jade-to-pug/jade/)
- [Migrate a Java Project From Joda-Time to java.time](https://getrush.ai/run/migrate-joda-time-to-java-time/joda-time/)
- [Migrate a Maven Project From JUnit 4 to JUnit 5](https://getrush.ai/run/migrate-junit-4-to-junit-5/junit/)
- [Migrate dgrijalva/jwt-go to golang-jwt in a Go Auth Service](https://getrush.ai/run/migrate-jwt-go-to-golang-jwt/jwt-go/)
- [Replace lazy_static With std::sync::LazyLock in a Rust Project](https://getrush.ai/run/migrate-lazy-static-to-lazylock/lazy-static/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
