install asdf

$ git clone ~/.asdf
$ echo 'source ~/.asdf/' >> $ZDOTDIR/.zshrc

don’t install asdf via brew because:

install plugins

PLUGIN is a language like elixir or ruby:

$ asdf plugin-add PLUGIN
$ asdf list-all PLUGIN
$ asdf install PLUGIN 1.0.0
$ asdf global PLUGIN 1.0.0
$ asdf current PLUGIN

installed plugins and their versions are stored in ~/.asdf/installs/.

update plugins

$ asdf plugin-update ruby
$ asdf plugin-update --all



uninstall system Elixir before adding Elixir plugin:

$ brew uninstall --force elixir
$ rm -rf ~/.mix/



NOTE: asdf uses ruby-build to build and install Ruby under the hood.

add support for existing .ruby-version files after adding Ruby plugin:

# ~/.asdfrc

legacy_version_file = yes

use .ruby-version for legacy projects and .tool-versions for new ones.


When asdf-vm installs a package it creates shims for every executable program in that package in a $ASDF_DATA_DIR/shims directory (default ~/.asdf/shims). This directory being on the $PATH (by means of or is how the installed programs are made available in the environment.

=> this is exactly what rbenv does.

shims are not created automatically when language-specific package manager is used to install packages (say, bundler to install Ruby gems) - it’s necessary to create all missing shims for that language manually:

$ asdf reshim PLUGIN
/ or
$ asdf reshim PLUGIN VERSION

this must be the same as running rbenv rehash in case of rbenv.

in case of Ruby it’s always possible to run executable via bundle exec - even if its shim is not created:

$ bundle exec rails console


Add a .tool-versions file to your project dir and versions of those tools will be used. Global defaults can be set in the file $HOME/.tool-versions.

asdf global command writes specified tool version to ~/.tool-versions.


if you want to set a version only for the current shell session or for executing just a command under a particular tool version, you can set an environment variable like ASDF_${TOOL}_VERSION.

  " ~/.vim/vimrc

  Plug 'wincent/command-t', {
-       \   'do': 'cd ruby/command-t/ext/command-t && RBENV_VERSION=system ruby extconf.rb && make'
+       \   'do': 'cd ruby/command-t/ext/command-t && ASDF_RUBY_VERSION=2.6.5 ruby extconf.rb && make'
        \ }

NOTE: change ASDF_RUBY_VERSION to whatever Ruby version current MacVim bottle is compiled against so that Ruby versions match.


asdf: No version set for command rspec

$ bundle exec rspec
asdf: No version set for command rspec
you might want to add one of the following in your .tool-versions file:

ruby 2.6.5


this error just means that rspec gem is not installed - add it to Gemfile and bundle install.

UPDATE (2020-11-18)

Or else you might need to reshim ruby plugin:

$ asdf reshim ruby