Ruby Versions and Gems

19 Oct 2026

rbenv is a lightweight Ruby version manager for Unix-like systems, which dynamically intercepts Ruby executable commands using shims, switching versions by checking the RBENV_VERSION environment variable, searching per-project .ruby-version file, or falling back to the global ~/.rbenv/version file.

# install rbenv (Linux/macOS)
curl -fsSL https://rbenv.org/install.sh | bash

rbenv help                  # man rbenv: view help text for any rbenv command

rbenv install -l            # list latest stable versions for each Ruby
rbenv install <version>     # install a Ruby version:

rbenv versions              # list all locally installed Ruby versions known to rbenv
rbenv version               # view the currently active Ruby version

rbenv shell <version>       # set a shell-specific Ruby version
rbenv local <version>       # set a directory-specific Ruby version
rbenv global <version>      # set the global Ruby version

rbenv which <command>       # view the executable path that a command resolves to

RubyGems is the official package management framework for the Ruby programming language.

A gem is a standardized package containing a Ruby library or program, which includes metadata (such as a name, version, and platform), the executable code, documentation, and a .gemspec file.

The gem command-line tool can be used to discover, install, update, and manage these packages.

gem help                # view help text for any gem command

gem search <REGEXP>     # seach remote gems whose name matches the regexp

gem install <GEMNAME>   # install local or remote gem into a gem repository
gem uninstall <GEMNAME> # remove an installed gem

gem list <REGEXP>       # list installed Gems

The bundle is the command-line tool provided by the Bundler gem, which is designed to manage a project’s dependency.

bundle help  # view help text for each subcommand

gem install bundler      # install the latest Bundler
bundle update --bundler  # update the recorded version in `Gemfile.lock`

bundle install  # install the gems specified by the Gemfile or Gemfile.lock
bundle update   # update dependencies to their latest versions

bundle list     # list all the gems in the bundle
bundle outdated # list installed gems with newer versions available

bundle exec     # execute a script in the current bundle

bundle config   # specify and read configuration options for Bundler

Bundler is a default gem, so every Ruby installation always contains a version of it that cannot be uninstalled. Installing a newer version does not replace the default one. Both stay available.

Bundler supports overriding gem sources with mirrors to configure rubygems.org as the gem source in Gemfile while still using mirror to fetch gems.

bundle config set --global mirror.SOURCE_URL MIRROR_URL

For example, to globally mirror https://rubygems.org to an alternate public endpoint:

bundle config set --global mirror.https://rubygems.org https://example.org

Alternatively, to configure a mirror only for a project using a regional service:

bundle config set --local mirror.https://rubygems.org https://mirrors.tuna.tsinghua.edu.cn/rubygems/

Enable deployment mode in CI or on a deployment host so Bundler installs gems under vendor/bundle and refuses to change an out-of-date Gemfile.lock:

bundle config set --local deployment true

BUNDLE_DEPLOYMENT is equivalent to enabling BUNDLE_FROZEN and setting the installation path to vendor/bundle. BUNDLE_FROZEN prevents Bundler from making automatic changes to Gemfile.lock, so the lockfile must be committed and kept in sync with the Gemfile.

Enable lockfile checksums to record the expected checksum of each gem and reject a package whose contents differ from the recorded value:

bundle config set --local lockfile_checksums true
bundle lock --add-checksums  # add checksums to an existing lockfile

Some mirrors may publish incomplete or stale checksum metadata. If a mirror leaves checksum values absent, generate or refresh the lockfile using a mirror with complete metadata or the official source, then commit it; deployments can still download the gems from the mirror and verify them against the recorded checksums. Missing checksums are also expected for Git and path dependencies.

The settings are stored in .bundle/config; keep that file machine-specific and commit Gemfile.lock instead.

A Gemfile is a file that describes an application’s gem environment for Bundler, which is evaluated as Ruby code, in a context which makes available a number of methods used to describe the gem requirements.

A Gemfile.lock is the output of dependency resolution, recording the exact version of every gem, direct or transitive.