Ruby versions

Butler manages Ruby versions through rv. Versions are prebuilt downloads, so installing a Ruby takes seconds rather than the several minutes a source build costs.

Install Ruby

Ruby support comes from the rv component:

butler install rv
butler rv ruby install 3.4
butler rv ruby install 3.3

List what’s installed, or ask which Ruby applies where you are:

butler rv ruby list
butler rv ruby find

The Ruby tab in the menu bar app offers the same actions, and appears once rv is installed.

Run ruby, bundle and gem

After shell integration, ruby, bundle, bundler, gem, rake and irb are on your PATH and resolve the version for the directory you’re in — a project’s .ruby-version, else your default:

ruby -v
bundle install
bundle exec rspec

Or reach rv directly:

butler rv run ruby -v

bundle exec works outside your terminal

If you run Fastlane, RuboCop or RSpec from anything other than an interactive shell, this is the point of the whole feature.

A version manager’s shell hook only runs in an interactive shell. Your editor, a build script, a git hook and CI all inherit PATH and nothing else — so they get the system Ruby, and bundle exec fails with a version or gem mismatch that looks nothing like a version-manager problem.

Butler installs real files on PATH, so those callers resolve exactly what your terminal does, with no profile to source first.

Put Butler’s toolchain on your PATH

butler shell install

Open a new terminal, then confirm what’s resolving:

butler doctor

Doctor names the Ruby each shim resolves to, flags anything earlier on PATH shadowing Butler’s, and warns when the same version exists in two places — which matters more than it sounds, because gems live beside the interpreter. Two copies of Ruby 3.4 means two different gem sets, and which one you get can differ between your terminal and your build.

Moving from rbenv, rvm or chruby

They all put a ruby on your PATH and expect to manage it. Running one alongside Butler causes version flip-flopping depending on which initializes last. Remove the other manager’s lines from your shell RC once you’ve moved over; butler doctor will tell you if something is still competing.

Where the versions live

Butler installs Rubies to ~/.local/share/butler/runtimes/rv.

That’s outside Butler’s usual state directory for one specific reason: Bundler writes the Ruby’s library path into RUBYOPT, and Ruby splits that variable on whitespace with no way to quote or escape a path. Butler’s normal home is inside Application Support — the space breaks every bundle exec — so Rubies get a space-free path of their own.

RUBIES_PATH is a search list, so if you already used rv, the Rubies you had stay where they are and keep working. Butler adds its directory rather than taking anything over.