Minari for Offline Reinforcement Learning Datasets

Minari's Offline RL Dataset Boundary

Minari addresses a specific problem in offline reinforcement learning: datasets collected from an environment are often stored in incompatible formats, making them harder to exchange between researchers and training libraries. The README describes Minari as an offline counterpart to Gymnasium and an offline RL counterpart to HuggingFace's datasets library. That comparison identifies the library's scope. Minari concerns dataset storage, retrieval, creation, and access rather than the policy learning method itself.

The intended users are Python researchers working with offline RL, particularly those collecting episodes from Gymnasium environments or retrieving existing datasets. The repository lists TorchRL, d3rlpy, and AgileRL as training libraries that integrate with Minari. These integrations place Minari below the training layer. It provides data that an offline RL algorithm can consume, while the algorithm remains responsible for selecting actions during collection or learning a policy from stored transitions.

The project does not claim to be a general-purpose dataset conversion service, a simulator, or a complete offline RL training stack. Its standard format is most relevant when a workflow needs repeatable loading and episode-level access to observations, actions, rewards, terminations, truncations, and information fields. A project that only needs a few local arrays may not need this abstraction. A multi-dataset research workflow can benefit from a common package and command-line discovery model.

Episode Data Flow Through Minari

The repository layout and README show a library implementation under `minari/`, a command-line entry point, documentation, tests, and packaging configuration. The basic data-access path is explicit: `minari.load_dataset()` loads a named dataset, and `dataset.iterate_episodes()` exposes episode records. Each record exposes `observations`, `actions`, `rewards`, `terminations`, `truncations`, and `infos`.

The distinction between `terminated` and `truncated` is retained in the episode data. In the writing example, a collection environment computes a single `done` value from the `terminated` and `truncated` results returned by `env.step(action)`. The recorded dataset preserves both fields separately. This is useful for offline RL because terminal states and time-limit truncation represent different episode boundaries. Minari's API therefore does not collapse all episode endings into one undifferentiated signal.

Dataset creation follows a different path. `DataCollector` wraps a Gymnasium environment. A caller resets the environment, samples actions from `env.action_space.sample()`, steps the environment, and accumulates the returned data through the collector. Once collection finishes, `env.create_dataset("frozenlake/test-v0")` creates a named dataset. The example uses `FrozenLake-v1`, so collection relies on the ordinary Gymnasium environment interface rather than a Minari-specific simulator.

Optional dependencies indicate several storage and integration paths. `pyarrow` supports the `arrow` extra, `h5py` supports `hdf5`, `google-cloud-storage` supports `gcs`, and `huggingface_hub` supports `hf`. The `create` extra installs `jax[cpu]`. The package can remain small for basic use while allowing a caller to add the backend needed for a workflow.

Installing Minari and Inspecting Remote Data

The README instructs users to install the package from PyPI:

pip install minari

This installs the minimum required dependencies. The package metadata requires Python `>= 3.11` and lists `numpy>=2.0.0`, `typing_extensions>=4.4.0`, `typer>=0.9.0`, `gymnasium>=0.28.1`, and `packaging` among its core dependencies.

For users who want all optional dependencies immediately, the documented command is:

pip install "minari[all]"

The `all` extra combines the `arrow`, `hdf5`, `gcs`, `hf`, and `create` extras. A narrower install can suit a workflow that uses only one backend, although the README does not provide separate installation commands for those extras.

The command-line interface can inspect remote datasets:

minari list remote

The README shows downloading a specific D4RL dataset with:

minari download D4RL/door/human-v2

After downloading, a user can inspect local datasets with `minari list local` and inspect one dataset's details with `minari show D4RL/door/human-v2`. The complete command list is available through `minari --help`. The README does not document authentication requirements, download destinations, retry behavior, or dataset removal, so those details need checking before automation.

Creating a First FrozenLake Dataset

A first local use can follow the README's `FrozenLake-v1` example. The environment is wrapped with `DataCollector`, which records episodes as the environment is stepped:

import minari
import gymnasium as gym
from minari import DataCollector


env = gym.make('FrozenLake-v1')
env = DataCollector(env)

The collection loop resets the environment, samples actions from its action space, and records the result of each `env.step(action)` call. It ends when either termination or truncation occurs:

for _ in range(100):
    env.reset()
    done = False
    while not done:
        action = env.action_space.sample()
        obs, rew, terminated, truncated, info = env.step(action)
        done = terminated or truncated

After collection, the named dataset is created:

dataset = env.create_dataset("frozenlake/test-v0")

A dataset can then be loaded through the Python API. The README's reading example accesses each episode through `iterate_episodes()` and reads the episode fields directly:

import minari

dataset = minari.load_dataset("D4RL/door/human-v2")

for episode_data in dataset.iterate_episodes():
    observations = episode_data.observations
    actions = episode_data.actions
    rewards = episode_data.rewards

The collection example uses random actions. It demonstrates the format rather than policy quality. A researcher collecting useful behavior data must supply a policy in place of `env.action_space.sample()`, as noted by the README comment.

Minari Compared with D4RL and Direct File Loading

Minari's practical alternative is direct loading of dataset files or adopting a project-specific collection pipeline. Direct loading gives the caller control over the file format and parsing code, but it does not provide Minari's named dataset discovery, download command, or common episode API. If a project already has a stable local format and no need to share data with another tool, direct file access may be simpler.

D4RL provides a useful comparison because the README uses `D4RL/door/human-v2` as a downloadable dataset name and links a tutorial that recreates the Maze2D datasets from D4RL. The repository positions Minari as a format and dataset-management layer rather than as a replacement for every component around D4RL. A caller can use Minari to load a dataset while relying on another library for environment behavior or offline RL training.

The difference is workflow-level. D4RL dataset names appear as data available through Minari, while Minari supplies the Python and CLI access mechanisms. Direct loading requires the caller to understand the files already used by that project. Minari reduces variation when several environments or datasets need a common access pattern. The trade-off is another abstraction and package dependency, along with the need to identify the correct optional backend when a dataset uses non-default storage.

Operational Limits, License Text, and Upgrade Cost

The clearest limitation is that the README does not explain how to convert arbitrary existing datasets into Minari format. The repository description establishes a standard format, remote dataset access, local listing, and dataset creation, but the documented workflow does not present a migration command for legacy files. A researcher with files in an unsupported layout may need to implement or obtain conversion code outside that workflow.

The storage model is configurable rather than uniform. The package supports multiple optional dependency groups, but the README does not state which backend is used for every dataset or how a caller selects one. This flexibility accommodates different data sources, yet adoption requires checking the backend needed by the target datasets. The `gcs` extra includes `google-cloud-storage`, which may introduce cloud configuration concerns for remote data, although the README does not document credential setup or deployment settings.

The repository is not archived, and its last push was on 2026-10-14. Recent releases include `v0.5.4` on 2026-09-13, `v0.5.3` on 2025-04-17, and `v0.5.2` on 2024-12-09. The package metadata labels the project `Development Status :: 4 - Beta` and supports Python 3.11 through Python 3.14. Upgrade planning should account for format compatibility between Minari versions and datasets, although the README does not define a versioned migration or rollback procedure.

The repository metadata describes the license as a custom license not classified by GitHub, while `pyproject.toml` declares `MIT License`. Because the text of `LICENSE` is not reproduced in the README excerpt, license obligations should be checked against that file rather than inferred from package metadata alone. This is a documentation check, not legal advice.

Choosing an Adoption Path for Minari

Minari suits an offline RL research team that wants one dataset interface across locally collected episodes and downloadable datasets. The `DataCollector` path is straightforward for Gymnasium environments, while `iterate_episodes()` exposes observations, actions, rewards, termination data, truncation data, and `infos`. Teams organized around TorchRL, d3rlpy, or AgileRL have named integration points to investigate before committing to the project.

Minari is a poor fit for a small script that only needs an in-memory array or for a project that cannot accept the Python `>= 3.11` requirement. It is also a poor fit when the central requirement is to train offline RL policies from one fixed file format, because Minari presents itself as the dataset layer rather than the training algorithm. The README does not document rollback, conversion from arbitrary datasets, cloud credential setup, or the exact license text, so those gaps should remain part of the evaluation.

Before adoption, inspect `LICENSE` and `pyproject.toml`, confirm the Python version, identify the optional backend for the target dataset, and run a small collection and reload workflow using `DataCollector` and `load_dataset()`. That sequence tests the project-specific questions that determine whether Minari fits the research workflow.

Editorial conclusion

Minari is appropriate for researchers who want a shared offline RL dataset interface and practical collection utilities. It is less suitable for projects that require a complete training stack or an undocumented conversion path. Verify Python 3.11 or newer, the required storage backend, the `LICENSE` file, and the dataset's episode structure before adoption.

Frequently asked questions

Official sources

1. Farama-Foundation/Minari on GitHub
2. Issues
3. Project website
4. README
5. Releases