# asdf-ruby is the plugin that makes asdf able to build Ruby

> The asdf-ruby plugin is a thin layer over ruby-build that gives the asdf version manager the ability to compile and install Ruby versions, and the configuration surface is three environment variables and a text file of default gems.

**asdf-vm/asdf-ruby** — Ruby plugin for asdf version manager

- Repository: https://github.com/asdf-vm/asdf-ruby
- Website: https://github.com/asdf-vm/asdf
- Stars: 733 · Forks: 157
- Language: Shell
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/asdf-vm-asdf-ruby

## asdf does the switching, ruby-build does the compiling

asdf-ruby is a Ruby plugin for the asdf version manager, and the split of responsibility is clean. asdf handles the per-project version selection through its .tool-versions file, and the plugin handles installing a specific Ruby version when you ask for one. Under the hood, asdf-ruby uses ruby-build to build and install Ruby, and the README points at the ruby-build readme for build options and a troubleshooting wiki page for installation issues. The practical consequence is that the plugin is a shell script layer over a mature build tool rather than a Ruby implementation of its own, which is why its own documentation is short and refers you to ruby-build for anything about compilation itself. The plugin repository holds bin/, lib/ and a rubygems-plugin/ directory, with the primary language recorded as shell, and the licence is MIT.

## Installing the plugin and the system dependencies is two separate jobs

The install step is one command that registers the plugin with asdf.

```
asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git
```

The README is emphatic about the ordering, though, because the failure mode is confusing. You should make sure you have the required system dependencies installed before trying to install Ruby, and it is also recommended that you remove other Ruby version managers before using asdf-ruby, a point that comes up again in the migration section. The system dependencies link goes to the suggested build environment page in the ruby-build wiki, which lists the libraries a Ruby source build needs. Installing the plugin first and then discovering that you are missing a compiler or a library produces an error that reads like a Ruby problem rather than a missing prerequisite, and the two-step advice in the readme is there to prevent exactly that.

## Three environment variables cover the unusual cases

Most of the time you run asdf install ruby and it works, and the configuration exists for the times it does not. First, RUBY_APPLY_PATCHES lets you apply custom patches before building, and the readme shows both a list of local patch files and a URL.

```
RUBY_APPLY_PATCHES=$'dir/1.patch\n2.patch\nhttp://example.com/3.patch' asdf install ruby 2.4.1
```

Second, ASDF_RUBY_BUILD_VERSION chooses which branch or tag of ruby-build to use, since by default asdf-ruby uses a recent release of ruby-build.

```
ASDF_RUBY_BUILD_VERSION=master asdf install ruby 2.6.4
```

Third, ASDF_GEM_DEFAULT_PACKAGES_FILE moves the file that lists default gems away from its default location. The default gems feature is worth a look on its own, because it solves a real annoyance. asdf-ruby can automatically install a set of default gems right after installing a Ruby version, and you enable it by providing a file at $HOME/.default-gems listing one gem per line.

```
bundler
pry
gem-ctags
```

## The plugin does not fetch new Ruby versions by itself

There is a note in the readme that explains a common confusion, and it is the one behaviour that trips up newcomers. This plugin does not automatically fetch new Ruby versions, so running asdf plugin update ruby will update asdf-ruby and ensure the latest versions of Ruby are available to install, and if the desired Ruby version is still not showing up, the troubleshooting section applies. The reason is that the list of installable versions comes from ruby-build, and the plugin pins a particular ruby-build release in lib/utils.sh. If a new Ruby has been released and your plugin has not been updated, the version is simply not in the list, and the fix is either asdf plugin update ruby or, if the plugin's pinned ruby-build needs updating, a pull request, with a note to check for an existing one before submitting a new one, and a workaround through ASDF_RUBY_BUILD_VERSION. The readme also points out that the plugin's RUBY_BUILD_VERSION is the setting that needs the update, which is a slightly confusing naming detail worth knowing before you go looking for it.

## Migrating from rvm or chruby takes one setting

The migration section is short and specific, because most of the work is done by asdf itself. asdf uses .tool-versions for auto-switching between software versions, and to ease migration you can have it read an existing .ruby-version file to find out what version of Ruby should be used. The switch goes in $HOME/.asdfrc.

    legacy_version_file = yes

If you are migrating from a version manager that supported fuzzy matching in .ruby-version, such as rvm or chruby, the readme warns that you might have to change .ruby-version to include a full version, for example changing 2.6 to 2.6.1. The other half of the advice is to completely uninstall the old version manager before installing asdf-ruby, which the troubleshooting section repeats. That recommendation is not about tidiness. Two version managers fighting over the same shims in your PATH produces a ruby that appears and disappears depending on the shell, and the type -a ruby check in the next section is how you diagnose it.

## The type -a ruby check is the diagnostic that matters

If you install asdf and asdf-ruby and it does not make ruby and irb available in your shell, the readme says to double check that you have installed asdf correctly, to make sure you have the system dependencies installed before running asdf install ruby, and then to run type -a ruby to see what rubies are currently on your PATH. The asdf ruby shim should be listed first. The correct output puts the shim at the top of the list.

```
ruby is /Users/someone/.asdf/shims/ruby
ruby is /usr/bin/ruby
```

And the incorrect output has only the system Ruby.

```
ruby is /usr/bin/ruby
```

That single check tells you which of the two failure modes you have. If the shim is missing from the list entirely, asdf is not installed correctly or not on your PATH. If the shim is there but not first, something else is putting a Ruby earlier in the PATH, which is exactly what happens when a previous version manager was left installed, and it is why the readme tells you to remove it rather than work around it.

## Conclusion

asdf-ruby suits a team that wants per-project Ruby versions managed by asdf, especially one moving from rvm or chruby, since the migration path is documented down to the legacy version file setting. It is the wrong tool if you install Ruby from a package manager, since the whole point is compiling from source, and the wrong tool if you want prebuilt binaries, because every install is a local build. Before adopting it, remove any other Ruby version manager, install the system dependencies first, and check the ruby-build version the plugin pins, because the most common complaint is a missing Ruby version and the fix is usually a plugin update. The last push was on 2026-10-13 and the repository publishes no releases.

## FAQ

### How do I install the asdf-ruby plugin?

Run asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git. The README also says to install the required system dependencies before trying to install Ruby, and to remove other Ruby version managers first.

### Why is the Ruby version I want missing from the asdf list?

The plugin does not automatically fetch new Ruby versions. Running asdf plugin update ruby updates asdf-ruby so the latest versions are available, and if the version is still missing, the plugin's RUBY_BUILD_VERSION in lib/utils.sh needs updating with the latest ruby-build release, which you can work around with ASDF_RUBY_BUILD_VERSION.

### How do I install default gems with every Ruby version under asdf?

Provide a file at $HOME/.default-gems that lists one gem per line, for example bundler, pry and gem-ctags. The location can be changed with the ASDF_GEM_DEFAULT_PACKAGES_FILE variable.

## Sources

- [asdf-vm/asdf-ruby on GitHub](https://github.com/asdf-vm/asdf-ruby)
- [Issues](https://github.com/asdf-vm/asdf-ruby/issues)
- [License: MIT](https://github.com/asdf-vm/asdf-ruby/blob/master/LICENSE)
- [Project website](https://github.com/asdf-vm/asdf)
- [README](https://github.com/asdf-vm/asdf-ruby/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/asdf-vm-asdf-ruby