Fixing `bundle install` on macOS if it fails with `cannot load such file -- rubygems/format (LoadError)`

On macOS, chances are that bundle install … fails with the following error:

/Library/Ruby/Site/2.0.0/rubygems/core_ext/kernel_require.rb:45:in `require': cannot load such file -- rubygems/format (LoadError)
       /Library/Ruby/Site/2.0.0/rubygems/core_ext/kernel_require.rb:45:in `require'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/source.rb:5:in `<top (required)>'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/dsl.rb:21:in `initialize'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/dsl.rb:6:in `new'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/dsl.rb:6:in `evaluate'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/definition.rb:18:in `build'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler.rb:144:in `definition'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/cli.rb:228:in `install'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/vendor/thor/task.rb:27:in `run'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/vendor/thor/invocation.rb:120:in `invoke_task'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/vendor/thor.rb:275:in `dispatch'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/vendor/thor/base.rb:408:in `start'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/bin/bundle:14:in `block in <top (required)>'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/lib/bundler/friendly_errors.rb:4:in `with_friendly_errors'
       /Library/Ruby/Gems/2.0.0/gems/bundler-1.2.3/bin/bundle:14:in `<top (required)>'
       /usr/local/bin/bundle:23:in `load'
       /usr/local/bin/bundle:23:in `<main>'
There was an error in your Gemfile, and Bundler cannot continue.

One common reason is that your Rubygems environment (the one specific to your current Ruby) or the is outdated. Specifically, you get this error when you have the Bundler gem in version 1.2.3 or lower installed.

Disclaimer

If you choose to follow the advice in this document, you will do so AT YOUR OWN RISK.

In particular, I do not recommend that you proceed without having a full backup of your whole system which has been fully tested and found to be actually restorable.

Prerequisites

macOS 10.11 or higher
Homebrew installed and working
A Ruby project where bundle install fails when you run it from inside the project directory

Troubleshooting

First, check whether you are currently on the macOS-provided system Ruby:

ruby -e 'puts Gem::RUBYGEMS_DIR'

If you are on the macOS-provided system Ruby

If you get the following output:

/Library/Ruby/Site/2.0.0

it means you’re on the macOS-supplied system Ruby. I recommend that you switch to a different Ruby and then restart the troubleshooting.
If you’re really determined to update your Rubygems environment (the one tied to your system Ruby!), run the following AT YOUR OWN RISK:

# To update the Rubygems environment tied to your *system* Ruby,
# paste and run the following Bash snippet (including parentheses)
# AT YOUR OWN RISK:

(
  set -eu

  EXPECTED_GEM_DIR='/Library/Ruby/Site/2.0.0'
  ACTUAL_GEM_DIR="$(/usr/bin/ruby -e 'puts Gem::RUBYGEMS_DIR')"
  if [[ "${EXPECTED_GEM_DIR?}" != "${ACTUAL_GEM_DIR?}" ]]; then
    echo 'This script requires system Ruby to be active.' >&2
    exit 1
  fi

  brew uninstall -f system-gem-executables
  sudo /usr/bin/gem update -n "$(mktemp -d)" -N --system

  PACKAGE_VERSION="$(/usr/bin/ruby -e \
    'puts "#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}"')"
  KEG="$(brew --cellar)/system-gem-executables/${PACKAGE_VERSION?}"
  mkdir -p "${KEG}/bin"

  sudo /usr/bin/gem install -n "${KEG}/bin" bundler
  brew link system-gem-executables
)

If you are on a custom Ruby

If you run ruby -e 'puts Gem::RUBYGEMS_DIR' and its output is something OTHER THAN /Library/Ruby/Site/2.0.0, it’s very likely that you’re currently on a custom Ruby.
To update your current Rubygems environment, run the following AT YOUR OWN RISK:

# To update your custom Rubygems environment, run the following
# shell commands AT YOUR OWN RISK:

gem update --system
gem install bundler
gem install hpricot rdiscount -N

claui/fix-bundle-install-on-macOS-cannot-load-such-file-rubygems-format-load-error.md