Requiring a file or library in Ruby

In this article we’re going to explore the following topics:

• the difference between an absolute and a relative path
• the Kernel#require method
• the Kernel#require_relative method

Absolute path vs Relative path

An absolute path is a full path that points to the same location regardless of the position of the current directory

$> tree
.
├── file1.txt
├── directory/
│   └── file2.txt
├── another_directory/
│   └── file3.txt
2 directories, 3 files
$> pwd
/Users/mehdi/path

Let’s cat the file3.txt file by using an absolute path

$> cat /Users/mehdi/path/another_directory/file3.txt
I'm the file #3
$> cd directory && pwd
/Users/mehdi/path/directory
$> cat /Users/mehdi/path/another_directory/file3.txt
I'm the file #3

First, we cat the file3.txt file by using an absolute path.

Then, we move to the directory subfolder.

Finally, we can see that calling cat with an absolute path will display the content of the file3.txt file regardless of the position of the current directory.

By contrast, a relative path starts from the current working directory

$> cat another_directory/file3.txt
I'm the file #3
$> cd directory && pwd
/Users/mehdi/path/directory
$> cat ../another_directory/file3.txt
I'm the file #3

Here, we cat the file3.txt file by using a relative path.

After, we move to the directory folder.

Then we can see that calling cat with a relative path — including the ../ prefix to move to the previous directory — will display the content of the file regarding the position of the current directory.

Kernel#require

The Kernel#require method loads the file or the library passed as a parameter.

This method expects that the argument includes an absolute path.

Otherwise, the method tries to find the file or library by prepending it with each path included in the $LOAD_PATH global variable — or with the current working directory path if ./ prepend the argument passed to the require method.

When the file or library is loaded then the absolute path is added to the $LOADED_FEATURES global array.

The $LOADED_FEATURES global array is used to check if a file or a library (a.k.a feature) has already been required. If so, the file or library is not loaded again and the Kernel#require method returns false.

Let’s have a look at the following example to detail the behavior of this method

$> tree
.
├── hello.rb
0 directories, 1 file

So, let’s try to require hello.rb within a script in the same directory

Here we pass the ./hello.rb argument to require. Because the argument is prepended by ./ then require determines an absolute path based on the current working directory.

When the file is loaded, the determined absolute path is added to the $LOADED_FEATURES global array.

Finally, because hello.rb is included in the $LOADED_FEATURES array then, a second call to require './hello.rb' returns false .

Now, let’s try to require the rake gem

Here we pass the rake argument to require. In this case, require tests each absolute path included in the $LOAD_PATH global array.

If a path matches, then the library is loaded and the path is added in the $LOADED_FEATURES array.

Finally, because the rake library is included in the $LOADED_FEATURES array then, a second call to require 'rake' returns false.

the require_relative method

The Kernel#require_relative method loads the file or library passed as a parameter.

It first finds the required file or library path, and then determines an absolute path according to the required file or library.

When the file or library is loaded then the absolute path is added to the $LOADED_FEATURES.

Let’s try to require the hello.rb file by using the Kernel#require_relative method

This script runs in the same directory as our hello.rb file.

The current script path is /Users/mehdi/require/.

So the require_relative method adds the path passed as an argument and determines an absolute path.

In this case, the final absolute path is /Users/mehdi/require/hello.rb.

If this path exists then the absolute path will be added to the $LOADED_FEATURES array.

Feel free to have a look to the Loading a file in Ruby article.

Ruby Mastery

We’re currently finalizing our first online course: Ruby Mastery.

Join the list for an exclusive release alert! 🔔

🔗 Ruby Mastery by RubyCademy

Also, you can follow us on x.com as we’re very active on this platform. Indeed, we post elaborate code examples every day.

💚