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

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 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 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 handles Windows-specific logic including RubyInstaller integration, while the Unix implementation resides in the corresponding 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 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.

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

mise install ruby@3.2.2

For Windows users, the installation process defined in 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.

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 file in your project root. This ensures all developers and CI/CD pipelines use the exact same Ruby version.

mise local ruby@3.3.0

The resulting .mise.toml file contains:

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

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.

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.

mise update ruby

Uninstalling Versions

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

mise uninstall ruby@3.1.4

Command Parsing and Execution

The CLI argument processing in 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, 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 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) 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}