Following the Path

Joël Quenneville
require "user"

Where is the user.rb file located? Perhaps in the current directory? That’s a trick question. There isn’t enough information to determine that from that single line.

The answer is more complex, flexible, and involves some UNIX history.


$LOAD_PATH is a global variable in Ruby that points to an array of path strings. The following is the (truncated) result of viewing $LOAD_PATH in pry:

[1] pry(main)> $LOAD_PATH

The paths are mostly going to various gem’s lib/ directories or Ruby installations. When executing require "user, Ruby looks for a file named user.rb in all of these locations.

What if there’s a user.rb in several of the locations? Ruby will load the first one it finds.

Gems will automatically add themselves to your load path.

Custom load path

That’s all great but what about adding your own paths? This can be accomplished by mutating the $LOAD_PATH. Using Array#unshift will prepend your path:

$LOAD_PATH.unshift File.expand_path(".", "lib")

Now require "user" will first look for ./lib/user.rb.

Complex paths

The same logic applies to more complex requires:

require "/api/client"

would look for /api/client.rb in all of the paths, starting with ./lib/api/client.rb


UNIX systems take a very similar approach with the environment variable $PATH. A (truncated) path might look like:

$ echo $PATH

$PATH is a list of paths separated by colons. When you type a command into the shell, it looks at all these locations for an executable matching the name you typed and will execute the first one it finds.

This is why some tool installation guides ask you to modify $PATH in your shell config.

You can see which path your shell is using for a given command with which

$ which ls

Sometimes you will have multiple versions of a command installed. For example psql from Homebrew and psql from The which command is is great for finding out which one is being used. Use this info to tweak your $PATH to ensure the right one loads. You can also use the -a flag on which to show all installed executables:

% which -a psql

Wandering off the path

Ruby has another way of requiring code:

require_relative "./lib/user"

Now where is user.rb located? This doesn’t use $LOAD_PATH. Instead it looks for ./lib/user.rb relative to the location of the current file.

Both require and require_relative take a path to a Ruby file without the .rb extension.

A few UNIX shell commands are hard-coded into the shell and don’t use the $PATH lookup system. For example, where is the which executable?

$ which which
which: shell built-in command