Ruby

mise installs Ruby from precompiled binaries where they exist and compiles it with ruby-build otherwise. On Windows it installs RubyInstaller2 builds.

Quick start

Select Ruby for the current project and check its executable:

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

mise use writes ruby = "4.0" to mise.toml. Use mise use -g [email protected] for a personal default. In an existing Bundler project, run mise exec -- bundle install, then prefix application commands with mise exec -- bundle exec. See the Ruby cookbook for a Rails project.

Choosing a version

Request	Selects
[email protected]	The newest 4.0.x release
[email protected]	That release
ruby@latest	The newest CRuby release
ruby@truffleruby	The newest TruffleRuby
ruby@jruby	The newest JRuby

Implementations other than CRuby use the names of ruby-build's definitions and always install through ruby-build (or ruby-install). List every version with mise ls-remote ruby.

Version files

mise can read .ruby-version and the Ruby version in a Gemfile. Enable them for Ruby:

mise settings add idiomatic_version_file_enable_tools ruby

This changes your global config. Add --local to enable it in the project's mise.toml instead, so teammates get the same behavior. See idiomatic version files.

mise then reads .ruby-version (a leading ruby- is ignored), a ruby "4.0.7" line in Gemfile, or Bundler's ruby file: ".ruby-version", which is resolved next to the Gemfile. To write .ruby-version from the selected Ruby:

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

Gems and Bundler

gem install installs into the selected Ruby version, and so does bundle install unless Bundler is configured with a path. Installed gems are therefore not available after you switch versions. mise adds a RubyGems plugin to each Ruby it installs. The plugin runs mise reshim after gem and Bundler installs, so new executables get shims. While RubyGems runs, the plugin also adds the Ruby's lib/pkgconfig directory to PKG_CONFIG_PATH, so native extensions find the libraries bundled with precompiled Rubies. mise sets no Ruby environment variables of its own.

To keep a Ruby CLI across Ruby versions, install it as its own tool with the gem backend, for example mise use -g gem:rubocop.

How mise installs Ruby

Precompiled binaries

By default mise downloads a precompiled CRuby from jdx/ruby and verifies its GitHub artifact attestation (ruby.github_attestations). Precompiled binaries are available for:

• macOS on arm64 (Apple Silicon)
• Linux on arm64 and x86_64, with glibc (manylinux2014)

If no precompiled binary exists for your platform or Ruby version, mise compiles Ruby with ruby-build instead. To always compile, set ruby.compile to true:

mise settings ruby.compile=true

jdx/ruby has no musl builds, so on musl systems such as Alpine mise compiles Ruby. On Alpine and NixOS, mise also compiles by default, because all_compile defaults to true there; this default is deprecated and changes in mise 2027.8.0. If you host your own musl binaries with ruby.precompiled_url, set ruby.precompiled_arch and ruby.precompiled_os to use them.

Precompiled binaries only

Set ruby.compile to false on hosts without a build toolchain, where falling back to ruby-build would fail late or pull in build dependencies:

mise settings ruby.compile=false

Installs then fail when no precompiled binary exists for the requested version and platform. mise ls-remote ruby and prefixes such as ruby = "4.0" only consider versions with a precompiled binary, so a prefix resolves to the newest 4.0.x that has one. With a custom ruby.precompiled_url template, mise cannot list the available binaries and leaves version listings unfiltered.

Rebuilt binaries

jdx/ruby sometimes publishes a new build of a Ruby version without changing the version, for example to fix packaging. Each build has its own release tag, such as 3.3.11-1 or 3.3.11-2; mise still treats the version as 3.3.11. Without mise.lock, an install picks the newest build. With mise.lock, the locked URL fixes the build:

mise.lock

[[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 move to the newest build of the same version, delete the Ruby entry from mise.lock, or every Ruby platform url, then run:

mise lock ruby
mise install --force ruby

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

Compiling with ruby-build

Source builds use ruby-build and need its build dependencies. mise compares its copy of ruby-build with the latest ruby-build release before every source build and updates it when they differ. Set ruby.ruby_install to true to compile with ruby-install instead.

ruby.ruby_build_cli_opts passes flags to ruby-build itself, and ruby.ruby_build_opts passes arguments to Ruby's configure. For example, --keep preserves the source tree after installation, and RUBY_BUILD_BUILD_PATH chooses where it is kept:

mise.toml

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

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

Configure arguments, such as --enable-yjit, go in ruby.ruby_build_opts. mise passes them after ruby-build's -- separator:

mise.toml

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

ruby-build also reads its own environment variables, such as RUBY_CONFIGURE_OPTS, from the environment or from install_env.

Windows

On Windows, mise installs RubyInstaller2 builds. ruby.compile has no effect there.

Migrating from other Ruby managers

Projects set up for rbenv, rvm or chruby usually have a .ruby-version; enable it as described in Version files.

To reuse Rubies installed with Homebrew, link Homebrew's versioned [email protected] formulae into mise with mise sync ruby, then select one with mise use:

mise sync ruby --brew
mise ls ruby --installed

Troubleshooting

An installed plugin named ruby takes precedence over the built-in installer. If mise behaves differently from this page, check mise plugins ls and see selecting another implementation.

Missing Ruby versions

Ruby's version list normally comes from mise's versions host and is cached for fetch_remote_versions_cache. If a version you expect is missing, clear the cache and list again:

mise cache clear ruby
mise ls-remote ruby

With use_versions_host set to false, or with ruby.compile = false, mise lists versions with ruby-build itself and updates ruby-build first.

Tool options

Ruby has no Ruby-specific options. install_env reaches ruby-build or ruby-install, default gem installs and postinstall commands. Use it for a per-project override; use ruby.ruby_build_opts for a default across projects:

mise.toml

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

Other generic options are described in tool options.

Default gems file deprecated

mise installs the gems listed in ~/.default-gems (ruby.default_packages_file) into each new Ruby version. Each line names a gem, optionally followed by a version constraint (bcat ~> 0.6.0) or --pre, and # starts a comment. mise warns about this file from 2026.11.0 and stops reading it in 2027.11.0. Install Ruby CLIs with the gem backend instead, for example "gem:rubocop" = "latest", or use a postinstall command for gems every Ruby version needs.

Settings

Set these under [settings] in a config file, with mise settings set, or with a setting's environment variable where it has one. See which value wins when a setting is set in more than one place.

ruby.apply_patches

Patch files or URLs to apply to the Ruby source before compiling it, one per line.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_APPLY_PATCHES

[settings.ruby]
apply_patches = '''
https://example.com/fix.patch
/opt/patches/ruby-yjit.patch
'''

mise applies them through ruby-build, or ruby-install when ruby.ruby_install is on. Precompiled builds are not patched.

ruby.compile

Compile Ruby from source instead of using a precompiled build.

• Type: boolean
• Default: unset
• Environment variable: MISE_RUBY_COMPILE

false uses only precompiled builds: installs fail when none exists, and mise ls-remote and prefixes consider only versions that have one. When unset, all_compile decides; if that is unset too, mise uses a precompiled build when one exists and compiles otherwise. Has no effect on Windows, where mise installs RubyInstaller2 builds. See Precompiled binaries.

ruby.default_packages_filedeprecated

File listing gems to install into each new Ruby version.

• Type: string
• Default: "~/.default-gems"
• Environment variable: MISE_RUBY_DEFAULT_PACKAGES_FILE
• Deprecated: Default ruby gem files are deprecated. Use tool-level postinstall hooks for gems that should be installed into every ruby version, or use the gem: backend for CLI tools.

Each line names a gem, optionally followed by a version constraint or --pre. See Default gems file.

ruby.github_attestations

Verify GitHub artifact attestations of precompiled Ruby builds.

• Type: boolean
• Default: value of github_attestations
• Environment variable: MISE_RUBY_GITHUB_ATTESTATIONS

Applies when ruby.precompiled_url names a GitHub repository, such as the default jdx/ruby. Builds from a URL template are not checked.

ruby.precompiled_arch

Architecture name of precompiled Ruby builds, such as x86_64 or arm64, used with ruby.precompiled_os.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_PRECOMPILED_ARCH

mise uses it only when ruby.precompiled_os is also set, and then looks for <arch>_<os> builds instead of detecting the platform. Set both to use builds you host with ruby.precompiled_url for a platform jdx/ruby does not publish, such as musl Linux. See Precompiled binaries.

ruby.precompiled_os

OS name of precompiled Ruby builds, such as linux, used with ruby.precompiled_arch.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_PRECOMPILED_OS

See ruby.precompiled_arch.

ruby.precompiled_url

GitHub repository, as owner/repo, or URL template that mise downloads precompiled Ruby builds from.

• Type: string
• Default: "jdx/ruby"
• Environment variable: MISE_RUBY_PRECOMPILED_URL

A repository must publish releases with assets named like jdx/ruby's. A URL template can use {version}, {platform}, {arch} and {os}. {platform} is macos, arm64_linux or x86_64_linux, or <arch>_<os> from ruby.precompiled_arch and ruby.precompiled_os. {arch} and {os} are the parts of {platform} before and after its last _, such as x86_64 and linux; on macOS they are arm64 and macos. When both of those settings are set, {arch} and {os} are their values as given.

[settings.ruby]
precompiled_url = "https://mirror.example.com/ruby/ruby-{version}.{platform}.tar.gz"

With a URL template, mise cannot list which versions have builds, and it does not verify GitHub artifact attestations.

ruby.ruby_build_cli_opts

Options for ruby-build itself, such as --keep, passed before the version and install directory.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_BUILD_CLI_OPTS

ruby.ruby_build_opts

Arguments for Ruby's configure, such as --enable-yjit, passed through ruby-build.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_BUILD_OPTS

mise passes them after ruby-build's -- separator.

ruby.ruby_build_repo

Git repository or ZIP archive URL that mise gets ruby-build from.

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

ruby.ruby_install

Compile Ruby with ruby-install instead of ruby-build.

• Type: boolean
• Default: false
• Environment variable: MISE_RUBY_INSTALL

ruby.ruby_install_opts

Arguments for Ruby's configure, passed through ruby-install.

• Type: string
• Default: unset
• Environment variable: MISE_RUBY_INSTALL_OPTS

mise passes them after ruby-install's -- separator.

ruby.ruby_install_repo

Git repository or ZIP archive URL that mise gets ruby-install from.

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

ruby.verbose_install

Show ruby-build's full output while compiling Ruby.

• Type: boolean
• Default: unset
• Environment variable: MISE_RUBY_VERBOSE_INSTALL

When unset, it follows verbose.