Ruby

There is no AI here. All content is human-authored and tested for accuracy.

Check Ruby Gems and Bundler

How to manage Ruby gems on Mac. Understand the difference between RubyGems (the package manager) and Bundler (the project dependency manager). Update gems, speed up installation, and troubleshoot common gem problems.

Ruby has two layers of package management. RubyGems is the built-in tool that installs and updates individual gems. Bundler manages the exact set of gems a project needs, using a Gemfile and lockfile to keep dependencies consistent across machines. Most gem-related problems happen when these two layers get mixed together, so understanding the distinction matters before you start a project.

Installing Ruby is one step in setting up your Mac for development. See the Mac development setup guide.

Before you get started

You'll need a terminal application to install and use Ruby. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.

Speed up gem installation

By default, installing a gem also generates local documentation files. Many developers skip this step to save time, since gem documentation is easier to browse online.

To disable documentation for all future gem installs, add a configuration line to the .gemrc file in your home directory:

$ echo "gem: --no-document" >> ~/.gemrc

If you prefer to keep local documentation available, skip this step.

Understand RubyGems

RubyGems is the package manager built into Ruby. You use it to install gems (software libraries that add functionality to Ruby). Check your current RubyGems version:

$ gem -v

Modern Ruby releases (since Ruby 2.6) ship with a current version of RubyGems (and Bundler, too), so you typically do not need to update it after installing Ruby.

However, RubyGems gets updated more often than Ruby, so keep it updated with this command:

$ gem update --system

You'll see diagnostics plus an informative changelog showing what is new.

If you use a version manager such as Mise, rv, or chruby, the command updates RubyGems within that managed Ruby environment. If you accidentally run it against the macOS system Ruby (Ruby 2.6.10), it will fail because the system Ruby has restricted permissions. See the article Why You Shouldn't Use macOS System Ruby.

Understand Bundler

Bundler manages project dependencies. When you clone a Ruby project or start a new one, the project's Gemfile lists the gems it needs, and Gemfile.lock records the exact versions that were tested together. Bundler ensures everyone on the team uses the same gem versions.

To install a project's dependencies, run this command inside the project directory:

$ bundle install

This is often the first step to start work with a project. But before you do so, see below about how to check an old project before installing.

Bundler reads the project’s Gemfile and installs the gems that project needs, using the resolved versions from Gemfile.lock when available. For a project with a Gemfile, bundle install is the right choice; use gem install only for standalone gems or global tools, not for project dependency setup. The commands look similar but gem install puts gems in a global directory and those gems may conflict with a project's pinned versions (exactly what Bundler is designed to avoid).

When you run gem commands, prefix commands with bundle exec (for example, bundle exec rails server) to make sure you use the gem versions from the current project.

Check an old project before installing

When you clone or revisit an older Ruby project, do not run bundle install immediately. Bundler will read the BUNDLED WITH section in Gemfile.lock and automatically install whatever Bundler version the project was last locked with. If that version is too old for your current Ruby, Bundler will crash and leave the old broken version installed alongside your current one (see the DidYouMean troubleshooting section below).

Before running bundle install, check the lockfile for potential problems:

$ tail -3 Gemfile.lock

This shows the BUNDLED WITH version at the bottom of the lockfile. If it shows a Bundler version from a much older era (such as 1.x or early 2.x) and you are running Ruby 4.0, update the lockfile's Bundler version first:

$ bundle update --bundler

You can also check which Ruby version the project expects by looking at the top of the Gemfile for a ruby directive, or checking for a .ruby-version file. If the project targets a Ruby version much older than yours, expect some gems to need updating.

To see a summary of dependency issues without installing anything, run:

$ bundle check

This reports whether the dependencies in Gemfile.lock are satisfied without downloading or building anything. If it reports missing gems, that is normal for a freshly cloned project. However, if it reports version conflicts or incompatible Ruby requirements, you know to update the Gemfile before attempting a full install. For a complete project upgrade workflow, see Change the Ruby Version in a Project.

For projects that have not been maintained in a long time, a safer approach is to update all dependencies at once rather than trying to install the old locked versions:

$ bundle update

This resolves all gems fresh against the current Gemfile constraints and your installed Ruby version. Review and test the result before committing the updated lockfile.

Update gems in a project

To update gems within a Bundler-managed project, use Bundler commands rather than gem update. Running gem update updates gems globally, which can break projects that depend on specific versions.

To update a single gem in a project:

$ bundle update <gem-name>

To update all gems listed in your Gemfile:

$ bundle update

After updating, commit the changed Gemfile.lock to version control so your team stays in sync.

Troubleshoot gem problems

Bundler cannot reach RubyGems.org

If bundle install fails with network or timeout errors, check your Internet connection first. If the connection is fine, try switching the Gemfile source from http://rubygems.org to https://rubygems.org (confirm it uses HTTPS, not HTTP). Corporate networks and VPNs sometimes block gem downloads. You can test connectivity with:

$ gem fetch bundler

Bundler version mismatch

If you see something like Bundler 4.0.8 is running, but your lockfile was generated with 2.1.2. Installing Bundler 2.1.2 and restarting using that version, your installed Bundler is newer than the version recorded in the project's Gemfile.lock. Bundler detects the mismatch, installs the older locked version, and restarts the command with that version.

This can cause serious problems. The older Bundler may be incompatible with your current Ruby and crash (see the DidYouMean error below). Even if it does not crash, it will install outdated gem versions from the old lockfile, which may include gems with native extensions that fail to compile on your Ruby version. Letting Bundler silently downgrade itself is the start of a chain of failures.

Instead of allowing the downgrade, update the lockfile to use your current Bundler:

$ bundle update --bundler

This regenerates Gemfile.lock with your current Bundler version. Commit the updated lockfile so the rest of your team stays in sync.

If you see You must use Bundler 2 or greater with this lockfile, your Ruby environment has an older Bundler that cannot read the lockfile format. Update Bundler first:

$ gem install bundler

Then run bundle install again.

Bundler crashes with DidYouMean error

If you see DidYouMean::SPELL_CHECKERS.merge! errors when running any bundle command, the Bundler version in your environment is too old for your Ruby runtime. Newer Ruby versions removed or changed the DidYouMean API that older Bundler releases depend on, so Bundler crashes before it can do anything useful.

This is a Bundler compatibility error, not a problem with your project code. Because the old Bundler crashes immediately, you cannot use any bundle command to fix it. Even gem exec bundler may load the broken version. You must remove the old Bundler before the new one will work.

First, install a current Bundler and then remove the old version:

$ gem install bundler
$ gem uninstall bundler -v <old-version>

When prompted, select only the old version to uninstall. You can also remove all old versions at once with:

$ gem cleanup bundler

Verify that the new Bundler is active:

$ bundle -v

If you see a current version number, Bundler is fixed. Now update the project lockfile to record the newer Bundler:

$ bundle update --bundler

Commit the updated Gemfile.lock so your team stays in sync. If you use a version manager such as rv or Mise, run these commands inside that managed Ruby environment. This error is common when an old project lockfile pulls in a Bundler release from several major versions ago.

Native extension gems fail to build

Some gems include C extensions that must compile during installation. If a gem fails with compiler errors, the problem is usually a missing system library or an outdated gem rather than a Bundler issue.

After upgrading Ruby, you may see build failures from gems that use older C APIs. For example, upgrading to Ruby 4.0 can cause gems such as jaro_winkler to fail with incompatible function pointer types errors. The gem itself is outdated, not your Ruby installation. In most cases, the failing gem is pinned by an older dependency. For example, rubocop 0.80.1 pins jaro_winkler 1.5.4, which does not compile on Ruby 4.0. The fix is to update the parent gem in your Gemfile:

$ bundle update rubocop

Modern versions of most gems have dropped incompatible C extensions or updated their code for current Ruby. Gems, not Ruby itself, are usually the real upgrade bottleneck.

If the build failure is caused by a missing system library rather than an outdated gem, try these fixes:

  • Make sure Xcode Command Line Tools are installed: xcode-select --install
  • Install the required library through Homebrew (for example, brew install libpq for the pg gem)
  • Check the gem's documentation for macOS-specific build instructions

For more Ruby installation troubleshooting, see Troubleshoot Ruby Installation.

Gems installed globally conflict with a project

If bundle exec finds different gem versions than expected, you may have installed gems globally with gem install that shadow the Bundler-managed versions. Run bundle exec gem list inside the project to see what Bundler resolves. To avoid this, use bundle install for project work and reserve gem install for standalone tools.

Slow bundle install on a new machine

A fresh bundle install on a new machine can take several minutes because it downloads and compiles every gem from scratch. To speed up subsequent installs, Bundler caches downloaded gems. You can also run bundle install --jobs 4 to download gems in parallel.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.