# How to Use mise for Ruby Version Management: A Complete Guide

> Master Ruby version management with mise. Install versions, set up project environments, and run commands automatically with this complete guide.

- Repository: [jdx/mise](https://github.com/jdx/mise)
- Tags: how-to-guide
- Published: 2026-08-09

---

**Use mise for Ruby version management by leveraging its core **backend** plugin to install specific versions, configure project-local environments, and execute commands with automatic version switching via shims that delegate to the active Ruby binary.**

The **jdx/mise** repository provides a universal version manager that supports Ruby as a core language through dedicated backend implementations. Unlike external plugins, mise's Ruby support is built directly into the codebase, utilizing the `Backend` trait defined in [`src/backend/mod.rs`](https://github.com/jdx/mise/blob/main/src/backend/mod.rs) to handle installation, resolution, and execution across macOS, Linux, and Windows platforms.

## How mise's Ruby Backend Works

### Core Implementation Architecture

The Ruby functionality in mise relies on a trait-based backend system. The `Backend` trait in [`src/backend/mod.rs`](https://github.com/jdx/mise/blob/main/src/backend/mod.rs) defines the interface that every language plugin must implement, including methods like `latest_version` and `list_versions_matching` for resolving version strings. For Ruby specifically, mise provides platform-specific implementations: [`src/plugins/core/ruby_windows.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/ruby_windows.rs) handles Windows-specific logic including RubyInstaller integration, while the Unix implementation resides in the corresponding [`src/plugins/core/ruby.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/ruby.rs) file.

When you request a Ruby version, the backend queries remote sources to locate pre-compiled binaries or source archives. The system uses the `ruby_bin()` helper function found in [`src/system/packages/brew/source.rs`](https://github.com/jdx/mise/blob/main/src/system/packages/brew/source.rs) to verify binary availability, ensuring that system Rubies are detected before initiating new installations. After installation, mise places a **shim** named `ruby` on your `$PATH`, which forwards invocations to the exact binary matching your current context's version requirements.

## Installing Ruby Versions with mise

### Listing Available Versions

Before installing, query the remote version list to see all available Ruby releases. The backend parses official Ruby releases and RubyInstaller feeds to populate this list.

```bash
mise ls-remote ruby

```

This command triggers the `list_versions_matching` implementation in the Ruby backend, which supports non-SemVer identifiers like `truffleruby` or `jruby` in addition to standard version numbers.

### Installing Specific Versions

Install any version by specifying it with the `@` syntax. The installer downloads the appropriate archive for your platform and extracts it to `~/.mise/installs/ruby/<version>`.

```bash
mise install ruby@3.2.2

```

For Windows users, the installation process defined in [`src/plugins/core/ruby_windows.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/ruby_windows.rs) fetches binaries from the RubyInstaller2 feeds using the `rubyinstaller_url` logic, while Unix systems typically use pre-compiled binaries or build from source depending on availability.

## Configuring Ruby Versions

### Setting Global Defaults

Set a system-wide default Ruby version that persists across terminal sessions. This writes the configuration to `~/.config/mise/config.toml`.

```bash
mise global ruby@3.2.2

```

### Project-Local Configuration

Pin a specific Ruby version to a project directory by creating or modifying a [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) file in your project root. This ensures all developers and CI/CD pipelines use the exact same Ruby version.

```bash
mise local ruby@3.3.0

```

The resulting [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml) file contains:

```toml
[tools]
ruby = "3.3.0"

```

### Temporary Version Switching

Execute a single command with a specific Ruby version without altering your current environment. The `exec` command spawns a subshell with the requested version activated.

```bash
mise exec ruby@2.7.6 -- ruby -v

```

## Managing Ruby Installations

### Checking Active Versions

Verify which Ruby version is currently active in your shell. This queries the shim system to determine which installation directory is currently linked.

```bash
mise current ruby

```

### Updating Version Lists

Force a refresh of the remote version cache when new Ruby releases become available. This updates the backend's internal registry of installable versions.

```bash
mise update ruby

```

### Uninstalling Versions

Remove a specific Ruby version entirely from your system to reclaim disk space.

```bash
mise uninstall ruby@3.1.4

```

## Command Parsing and Execution

The CLI argument processing in [`src/cli/args.rs`](https://github.com/jdx/mise/blob/main/src/cli/args.rs) parses commands like `install ruby@3.2` and routes them to the appropriate backend methods. When running tasks defined in [`src/task/mod.rs`](https://github.com/jdx/mise/blob/main/src/task/mod.rs), mise checks the `task.tools` configuration to ensure required Ruby versions are installed before execution, preventing "command not found" errors in automated workflows.

## Summary

- **mise** manages Ruby through native backend plugins located in `src/plugins/core/`, with separate implementations for Windows and Unix systems.
- The `Backend` trait in [`src/backend/mod.rs`](https://github.com/jdx/mise/blob/main/src/backend/mod.rs) defines version resolution methods including `latest_version` and `list_versions_matching` that interpret strings like `latest`, `3.2`, or `truffleruby`.
- Use `mise install ruby@<version>` to download and install specific releases, stored in `~/.mise/installs/ruby/`.
- Configure project-specific versions with `mise local` (creates [`.mise.toml`](https://github.com/jdx/mise/blob/main/.mise.toml)) or system defaults with `mise global` (updates `~/.config/mise/config.toml`).
- The **shim** system intercepts `ruby` calls and delegates to the active version, enabling seamless switching between projects.

## Frequently Asked Questions

### How does mise resolve Ruby version strings like "latest" or partial versions?

The Ruby backend implements `list_versions_matching` to handle version resolution, allowing you to specify `ruby@latest` for the newest stable release, `ruby@3.2` for the latest patch in that minor series, or specific implementations like `truffleruby`. This logic is part of the `Backend` trait implementation in the core Ruby plugin files, which queries remote registries and caches results for performance.

### Where does mise store installed Ruby versions on my system?

Installations are stored in `~/.mise/installs/ruby/<version>/` by default, with shims placed in `~/.mise/shims/` that are added to your `$PATH`. The `ruby_bin()` helper function in [`src/system/packages/brew/source.rs`](https://github.com/jdx/mise/blob/main/src/system/packages/brew/source.rs) locates these binaries when the shim executes, ensuring the correct interpreter is invoked based on your current directory's configuration.

### Can I use mise to manage alternative Ruby implementations like JRuby or TruffleRuby?

Yes, the Ruby backend supports alternative implementations beyond MRI (Matz's Ruby Interpreter). Because the version resolution logic in [`src/plugins/core/ruby_windows.rs`](https://github.com/jdx/mise/blob/main/src/plugins/core/ruby_windows.rs) and its Unix counterpart handles various release feeds, you can install JRuby, TruffleRuby, or other compatible implementations using the same command syntax: `mise install ruby@truffleruby-24.0` or `mise install ruby@jruby-9.4`.

### How do I run a Ruby script with a specific version without changing my global default?

Use the `mise exec` command to spawn a temporary environment with the specified version. For example, `mise exec ruby@3.1.4 -- ruby script.rb` executes [`script.rb`](https://github.com/jdx/mise/blob/main/script.rb) using Ruby 3.1.4 regardless of your global or local settings. This creates an isolated shell session that does not modify your persistent configuration files.