Ruby

Like rvm, rbenv, or asdf, mise can manage multiple versions of Ruby on the same system.

The following are instructions for using the ruby mise core plugin. This is used when there isn't a git plugin installed named "ruby". If you want to use asdf-ruby then use mise plugins install ruby GIT_URL.

The code for this is inside the mise repository at ./src/plugins/core/ruby.rs.

Usage

The following installs the latest version of ruby-3.2.x (if some version of 3.2.x is not already installed) and makes it the global default:

mise use -g ruby@3.2

Behind the scenes, mise uses ruby-build to compile ruby from source. Ensure that you have the necessary dependencies installed. You can check its README for additional settings and some troubleshooting.

Precompiled Binaries experimental

With experimental = true enabled, mise can download precompiled Ruby binaries instead of compiling from source. This significantly reduces installation time.

mise settings experimental=true
mise use ruby@3.4.1

Precompiled binaries are sourced from jdx/ruby and are available for the following platforms:

• macOS (arm64/Apple Silicon only)
• Linux arm64
• Linux x86_64

If a precompiled binary is not available for your platform or Ruby version, mise automatically falls back to compiling from source using ruby-build.

To always compile from source even when precompiled binaries are available:

mise settings ruby.compile=true

You can also use a custom source for precompiled binaries by setting ruby.precompiled_url to either a GitHub repo (e.g., owner/repo) or a full URL template.

You can also install a specific ruby flavour. To get the latest version from a flavour, just use the flavour prefix.

mise use -g ruby@truffleruby            # latest version of truffleruby

Default gems

mise can automatically install a default set of gems right after installing a new ruby version. To enable this feature, provide a $HOME/.default-gems file that lists one gem per line, for example:

# supports comments
pry
bcat ~> 0.6.0 # supports version constraints
rubocop --pre # install prerelease version

.ruby-version and Gemfile support

mise uses a mise.toml or .tool-versions file for auto-switching between software versions. However, it can also read ruby-specific version files .ruby-version or Gemfile (if it specifies a ruby version).

Create a .ruby-version file for the current version of ruby:

ruby -v > .ruby-version

Enable idiomatic version file reading for ruby:

mise settings add idiomatic_version_file_enable_tools ruby

See idiomatic version files for more information.

Manually updating ruby-build

ruby-build should update daily, however if you find versions do not yet exist you can force an update:

mise cache clean
mise ls-remote ruby

Settings

ruby-build already has a handful of settings, in additional to that mise has a few extra settings:

ruby.apply_patches

• Type: string(optional)
• Env: MISE_RUBY_APPLY_PATCHES
• Default: None

A list of patch files or URLs to apply to ruby source.

ruby.compile

• Type: Bool(optional)
• Env: MISE_RUBY_COMPILE
• Default: None

Controls whether Ruby is compiled from source or downloaded as precompiled binaries. Requires experimental = true to be enabled.

• If unset or false: Try precompiled binaries first, fall back to compiling if unavailable
• If true: Always compile from source using ruby-build

Example to force compilation:

[settings]
experimental = true
ruby.compile = true

ruby.default_packages_file

• Type: string
• Env: MISE_RUBY_DEFAULT_PACKAGES_FILE
• Default: ~/.default-gems

Path to a file containing default ruby gems to install when installing ruby.

ruby.precompiled_arch

• Type: string(optional)
• Env: MISE_RUBY_PRECOMPILED_ARCH
• Default: None

[experimental] Override architecture identifier for precompiled Ruby binaries.

ruby.precompiled_os

• Type: string(optional)
• Env: MISE_RUBY_PRECOMPILED_OS
• Default: None

[experimental] Override OS identifier for precompiled Ruby binaries.

ruby.precompiled_url

• Type: string
• Env: MISE_RUBY_PRECOMPILED_URL
• Default: jdx/ruby

Can be either:

• A GitHub repo shorthand: "jdx/ruby" or "yourorg/ruby"
• A full URL template with variables: {version}, {platform}, {os}, {arch}

Examples:

[settings.ruby]
# Use a different GitHub repo
precompiled_url = "yourorg/ruby"

# Or use a custom URL template
precompiled_url = "https://my-mirror.example.com/ruby-{version}.{platform}.tar.gz"

ruby.ruby_build_opts

• Type: string(optional)
• Env: MISE_RUBY_BUILD_OPTS
• Default: None

Options to pass to ruby-build.

ruby.ruby_build_repo

• Type: string
• Env: MISE_RUBY_BUILD_REPO
• Default: https://github.com/rbenv/ruby-build.git

The URL used to fetch ruby-build. This accepts either a Git repository or a ZIP archive.

ruby.ruby_install

• Type: Bool
• Env: MISE_RUBY_INSTALL
• Default: false

Use ruby-install instead of ruby-build.

ruby.ruby_install_opts

• Type: string(optional)
• Env: MISE_RUBY_INSTALL_OPTS
• Default: None

Options to pass to ruby-install.

ruby.ruby_install_repo

• Type: string
• Env: MISE_RUBY_INSTALL_REPO
• Default: https://github.com/postmodern/ruby-install.git

The URL used to fetch ruby-install. This accepts either a Git repository or a ZIP archive.

ruby.verbose_install

• Type: Bool(optional)
• Env: MISE_RUBY_VERBOSE_INSTALL
• Default: None

Set to true to enable verbose output during ruby installation.