How does a Perl program know where to find the file containing Perl module it uses?

If my Perl program uses Perl modules, how will it determine where to find the file containing the module code?

For example, if the program contains:

use MyModule1;              # Example 1
use This::Here::MyModule2;  # Example 2

where will it look?

Perl interpreter (which runs your perl program) will use a special array called @INC to search for a file containing the module.

Each value in the @INC array is a directory name (but see note below); Perl will search within those directories in a loop using the rules specified below. (Please refer to this SO post for details of how the contents of @INC are determined).

If the module's file is not found after exhausting @INC, the program's compilation will be aborted with an error. If the module's file is found in one of the directories specified in @INC, the search is finished without looking at the rest of @INC.

The way Perl searches for a module file within each of the directories listed in @INC is as follows:

• First, it will separate the module name's hierarchical components (words separated by ::), into the last component - which will be used to form a file name - and a hierarchy path (all the components preceding the last ::).

  In case the module name has only one component (no ::, e.g. MyModule1 above), the hierarchy path is empty and the filename is the name of the module. In the second example in this question, the last component is MyModule2 and hierarchy path will be This::Here.

• The expected file name will be determined by appending the last component of the module name with a .pm extension. E.g. MyModule1.pm and MyModule2.pm in our examples.

  NOTE: Module names are obviously case sensitive on Unix and other operating systems where file/directory naming is case sensitive.

• The module's directory will be determined by:

  1. Taking the next directory from @INC - let's say /usr/lib/perl as an example

  2. Forming a sub-directory of that directory by taking the hierarchy path of the module name (if any) and replacing "::" with / or whatever character the operating system uses as directory separator. In our two examples, the first module will be searched for in /usr/lib/perl (no sub-directory) and the second in /usr/lib/perl/This/Here.

  3. NOTE: the above is a slight simplification - @INC may also contain subroutine references and object references, which load the modules as their custom code specifies instead of performing the lookup in the directory as specified in #2 logic above. That functionality appears to be very seldom used and this article assumes that entire @INC only contains directories.

Let's go over a specific example, assuming that your @INC contains two sub-directories: ("/usr/lib/perl", "/opt/custom/lib").

Then Perl would search as follows:

==========================================================================
| Module                | Try # | File to try               
==========================================================================
| MyModule1             | Try 1 | /usr/lib/perl/MyModule1.pm
| MyModule1             | Try 2 | /opt/custom/lib/MyModule1.pm
==========================================================================
| This::Here::MyModule2 | Try 1 | /usr/lib/perl/This/Here/MyModule2.pm
| This::Here::MyModule2 | Try 2 | /opt/custom/lib/This/Here/MyModule2.pm
==========================================================================

Please recall that Perl interpreter will STOP trying to search once it finds the file in one of the locations, without trying to see if the file is in later locations as well. E.g. if /usr/lib/perl/This/Here/MyModule2.pm exists, then Perl will not look for, nor care about the existence, of /opt/custom/lib/This/Here/MyModule2.pm.

NOTE: @INC is used whenever Perl interpreter is using require-like mechanism for importing Perl modules. This includes:

• require directive itself
• use MyModule statement (equivalent to require+import)
• use base (equivalent to require+"push @ISA")
• -M command line parameter