Ruby

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

Usage

Select Ruby for the current project and check its executable:

mise use [email protected]
mise exec -- ruby --version

Use mise use -g [email protected] for a personal default. For an existing Bundler project, run mise exec -- bundle install, then prefix application commands with mise exec -- bundle exec. See the Ruby cookbook.

By default, mise installs a precompiled Ruby binary when one is available and falls back to compiling from source with ruby-build. Source builds require the necessary dependencies. See the ruby-build README for additional settings and troubleshooting.

These instructions use mise's built-in ruby support. An installed external plugin with the same name can change the behavior; use mise plugins ls to check for overrides. See the core implementation for backend details.

Precompiled Binaries

mise downloads precompiled Ruby binaries by default. This significantly reduces installation time.

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

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

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

jdx/ruby has no musl builds, so on musl-based distros such as Alpine mise always compiles Ruby from source (unless you set ruby.compile=false, in which case installs error out). If you host your own musl binaries via ruby.precompiled_url, set ruby.precompiled_arch and ruby.precompiled_os explicitly to opt back in to precompiled installs.

Precompiled binaries only

Set ruby.compile=false to opt out of source builds entirely. This is useful on hosts without a build toolchain, where a silent fallback to ruby-build would fail late or pull in build dependencies you deliberately don't have:

mise settings ruby.compile=false

With this setting:

• Installs error out when no precompiled binary exists for the requested version and platform, instead of falling back to ruby-build.
• mise ls-remote ruby and fuzzy versions only consider versions that have a precompiled binary, so ruby = "4.0" resolves to the newest 4.0.x that actually has a binary rather than a version that would have to be built from source.

If you set a custom ruby.precompiled_url template, mise cannot enumerate available versions and version listings are left unfiltered.

ruby.compile has no effect on Windows, which installs Ruby from RubyInstaller2 rather than from jdx/ruby or ruby-build.

Precompiled build revisions

Precompiled Ruby binaries are released from jdx/ruby. Sometimes the binary for a Ruby version is rebuilt without changing the Ruby version itself. Those rebuilds use build revision release tags like 3.3.11-1 or 3.3.11-2. mise uses these build revision tags for jdx/ruby precompiled binaries instead of the floating base release tag.

Rebuilds are for changes to the portable binary package, not changes to Ruby's own version number. The jdx/ruby release history includes rebuilds for reasons such as:

• native gem packaging fixes
• CA certificate lookup fixes
• RI documentation packaging changes
• SLSA/provenance workflow fixes
• mass regeneration of existing releases

This list is not exhaustive.

mise still treats the Ruby version as 3.3.11. Without a mise.lock, mise uses the latest available precompiled build revision when resolving the install. That means reinstalling the same Ruby version later may pick up a newer rebuild if one was published.

With a mise.lock, the download URL records which precompiled build revision is used:

[[tools.ruby]]
version = "3.3.11"

[tools.ruby.platforms.linux-x64]
url = "https://github.com/jdx/ruby/releases/download/3.3.11-1/ruby-3.3.11.x86_64_linux.tar.gz"

To see which precompiled build revision you have, inspect the release tag in the platform url:

• /releases/download/3.3.11-1/ means build revision 1
• /releases/download/3.3.11-2/ means build revision 2

If the lockfile already points at a build revision such as 3.3.11-1, mise keeps using that exact revision for reproducibility. To update to the newest precompiled build revision for the same Ruby version, remove the entire Ruby entry from mise.lock or remove every Ruby platform url, then regenerate the lock entry and reinstall:

mise lock ruby
mise install --force ruby

Commit the updated mise.lock so other machines and CI use the same precompiled build revision.

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

mise settings ruby.compile=true

To require precompiled binaries and never compile, see Precompiled binaries only.

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 of a flavour, use the flavour prefix.

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

Default gems

::: warning Planned deprecation Default package files are deprecated. They are still supported for now, but mise will start warning in 2026.11.0 and support will be removed in 2027.11.0.

For Ruby CLIs, install the tool directly with the gem backend:

[tools]
"gem:rubocop" = "latest"

For gems that really should be installed into every Ruby version, use a tool-level postinstall hook:

[tools]
ruby = { version = "3.4", postinstall = "gem install rubocop" }

:::

mise can automatically install a default set of gems right after installing a new ruby version. To use this legacy 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

Tool Options

The following tool-options are available for the ruby backend. These options go in the [tools] section in mise.toml.

install_env

Set environment variables for ruby-build or ruby-install and default gem installation:

[tools]
ruby = { version = "latest", install_env = { RUBY_CONFIGURE_OPTS = "--disable-install-doc" } }

.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 the ruby-specific version files .ruby-version and Gemfile (if it specifies a ruby version). A Gemfile may pin ruby with ruby "3.3.6" or Bundler's ruby file: ".ruby-version" (the path is resolved next to the Gemfile).

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

mise exec -- ruby -e 'puts RUBY_VERSION' > .ruby-version

Write only the version number, not the full ruby -v banner. Then enable idiomatic version file reading:

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 versions you expect are missing, you can force an update:

mise cache clean
mise ls-remote ruby

Settings

ruby-build already has a handful of settings; in addition, mise has a few extra settings:

To pass options to ruby-build itself, use ruby.ruby_build_cli_opts. For example, --keep preserves the source tree after installation; set RUBY_BUILD_BUILD_PATH to choose where it is kept:

[settings.ruby]
ruby_build_cli_opts = "--keep"

[env]
RUBY_BUILD_BUILD_PATH = "{{ config_root }}/.ruby-build"

Arguments for Ruby's configure script, such as --enable-yjit, belong in ruby.ruby_build_opts. mise passes those after ruby-build's -- separator:

[settings.ruby]
ruby_build_opts = "--enable-yjit"