Fix Ruby require LoadError in Homebrew on macOS

This error is a Ruby require failure: Homebrew’s Ruby code tried to load one of its own internal files, utils/popen, but the file was not available where the installed Homebrew code expected it. You will learn how Ruby resolves required files, why this usually indicates an incomplete or mismatched Homebrew installation, and how to inspect and repair it safely.

Ruby programs can split code into multiple files. The require method loads another Ruby file before the current program continues.

For example, an application may contain:

require "utils/popen"

Ruby searches for a matching file, commonly utils/popen.rb, using its load paths and context configured by the application. If Ruby cannot find or load it, it raises:

LoadError: cannot load such file -- utils/popen

In this stack trace, utils/popen is an internal Homebrew source file, not a RubyGem that you would normally install with gem install. The file is expected to be part of the Homebrew checkout under its Library/Homebrew directory.

Therefore, the likely problem is not the listed RubyGems configuration. It is usually one of these:

• A Homebrew update was interrupted, leaving files from different revisions.
• The Homebrew directory was copied or restored incompletely.
• Internal Homebrew files were manually removed or edited.
• A Git checkout was switched to a revision that does not match the rest of the files.

The important distinction is: a missing application-owned file should be repaired by repairing that application, not by installing an unrelated gem.

Think of Homebrew as a binder of numbered instruction pages.

utils.rb says, “Before I continue, fetch page utils/popen.” Ruby looks in Homebrew’s binder for that page. If the page is missing—or the binder contains pages from two different editions—Ruby cannot continue and reports a LoadError.

RubyGems is a separate library shelf. Installing random books on that shelf does not replace a missing page from Homebrew’s own binder.

Ruby uses require to load reusable code from another file.

# File: greeting.rb
module Greeting
  def self.message(name)
    "Hello, #{name}!"
  end
end

# File: app.rb
require_relative "greeting"

puts Greeting.message("Ava")

Output:

Hello, Ava!

require_relative explicitly loads a file relative to the current source file. Library and application frameworks often use require instead, because they configure locations where Ruby should search.

A missing file produces a LoadError:

require "utils/popen"

LoadError: cannot load such file -- utils/popen

For Homebrew, do not modify its internal require statements to silence the error. The correct repair is to restore a consistent Homebrew installation containing the expected file.

Consider this simplified project layout:

my_tool/
├── app.rb
└── utils/
    └── popen.rb

app.rb contains:

require_relative "utils/popen"
puts "Tool started"

Execution proceeds as follows:

1. Ruby starts app.rb.
2. Ruby reaches require_relative "utils/popen".
3. Ruby constructs a path relative to app.rb: my_tool/utils/popen.rb.
4. If that file exists and loads successfully, Ruby continues.
5. Ruby prints Tool started.

If utils/popen.rb is deleted, step 4 cannot succeed. Ruby stops before printing anything and raises a LoadError.

The Homebrew stack trace follows the same sequence: utils.rb requires utils/popen, but the expected Homebrew file cannot be loaded.

File loading appears in many Ruby programs:

• Command-line tools: Load helper code for process execution, file handling, or command parsing.
• Web applications: Load models, services, configuration, and database code.
• Plugins: Load optional integrations only when a feature is enabled.
• Test suites: Load support helpers and shared setup code.
• Package managers: Load internal modules that download files, run system commands, and manage installations.

When a LoadError names a file inside the application’s own directory, investigate that application’s files first. When it names a third-party library such as json or some_gem_name, then dependency installation and version management may be relevant.

In real Ruby codebases, developers make file dependencies predictable with a few patterns.

Use require_relative for nearby project files

# lib/report.rb
require_relative "report/formatter"

This avoids depending on the current working directory or a globally configured load path.

Use require for installed libraries

require "json"
require "net/http"

These libraries are found through Ruby’s configured load paths or a dependency manager such as Bundler.

Validate external dependencies early

Command-line tools often fail with a clear message before doing work:

unless system("git --version > /dev/null 2>&1")
  warn "Git is required but was not found."
  exit 1
end

Repair source-controlled tools from version control

For a tool installed from Git, developers commonly inspect the checkout and restore tracked files. In the historical Homebrew layout shown by the stack trace, the repository root is typically /usr/local.

cd /usr/local
git status

If the checkout is known to be a Git-based Homebrew installation and local modifications are not needed, restoring it from its remote revision can repair deleted or mismatched tracked files:

cd /usr/local
git fetch --all --prune
git reset --hard origin/master

git reset --hard discards uncommitted changes in that directory. Review git status and back up anything important first. The appropriate remote branch can differ by installation age and Homebrew version, so confirm it with git branch -r instead of assuming origin/master exists.

If the checkout is not recoverable, reinstalling Homebrew using its current official installation instructions is generally safer than manually copying individual internal Ruby files.

Installing a gem named after the missing file

This is usually the wrong fix:

gem install popen

utils/popen is a Homebrew-internal path, not evidence that a gem named popen is required. Installing a similarly named gem can add confusion without restoring the missing Homebrew source file.

Editing Homebrew’s require line

Changing this:

require "utils/popen"

into a commented line may only move the failure later. Other Homebrew code likely depends on the methods in that file. Restore the proper source instead.

Running Homebrew with sudo

Avoid commands such as:

sudo brew update

They can create root-owned files in Homebrew directories, causing later permission errors. Fix ownership only when you understand why it is wrong, and use the installation method appropriate to your system.

Running a destructive Git reset without checking changes

This can erase local work:

git reset --hard

First inspect:

git status
git diff

Back up custom files before restoring a checkout.

Treating every LoadError as a RubyGems issue

A missing gem and a missing application file are different problems. Read the missing name and stack trace path. A path under Homebrew’s own source tree points to Homebrew’s installation state.

# Load a standard library, gem, or configured library file
require "json"

# Load a file relative to the current Ruby file
require_relative "helpers/formatting"

• LoadError means Ruby could not find or load a required file.
• Read the missing path and stack trace before installing anything.
• A missing path under Library/Homebrew usually means Homebrew itself is incomplete or inconsistent.
• RubyGems settings do not normally restore files shipped inside Homebrew.
• Check a historical Git-based Homebrew checkout with:

cd /usr/local
git status
git branch -r

• Back up local changes before using git reset --hard.
• Do not use sudo brew ... as a general fix.
• If repair is uncertain, reinstall Homebrew through its current official instructions.

Why does Homebrew show a Ruby error?

Older Homebrew versions were implemented largely in Ruby. When its Ruby files cannot load each other, Ruby displays the underlying LoadError.

Does cannot load such file -- utils/popen mean I need to install a gem?

Usually no. In this stack trace, utils/popen is referenced from Homebrew’s own Library/Homebrew source directory, so it is likely a missing or mismatched Homebrew file.

Why are my RubyGems paths shown in the error report?

They describe Ruby’s environment, but they do not prove that RubyGems caused the failure. The stack trace location is more useful: it points to Homebrew’s internal source.

How can I see whether the Homebrew file is missing?

For the historical layout in the question, inspect it directly:

ls -l /usr/local/Library/Homebrew/utils/popen.rb

If it is absent, do not download a random copy; restore a consistent Homebrew revision or reinstall.

Is git reset --hard safe for repairing Homebrew?

It can be effective for a Git-based checkout, but it deletes uncommitted changes. Run git status, review your changes, and back up custom work first.

Can I fix this by changing RUBYLIB or GEM_PATH?

Changing global Ruby paths is not the normal fix and can create new conflicts. Repair the broken Homebrew files instead.

Why might old instructions not match my Mac?

Homebrew’s installation layout and supported Ruby versions have changed over time. The /usr/local/Library/Homebrew paths in this error indicate an older installation, so use current official reinstall guidance when rebuilding it.

• Ruby require — Loads standard libraries, gems, and configured project files.
• Ruby require_relative — Loads files relative to the current source file and is useful for project-owned code.
• Ruby load paths ($LOAD_PATH) — Explains where require searches for files.
• RubyGems — Manages third-party Ruby libraries, but does not usually repair application-owned files.
• Bundler and Gemfile — Provides repeatable dependency versions for Ruby applications.
• Git checkout recovery — Restores deleted or mismatched tracked files in source-controlled tools.
• Command-line troubleshooting — Uses stack traces, file inspection, and version-control status to locate failures.
• Homebrew installation and updates — Helps distinguish a broken package-manager installation from a package problem.