Perl modules FAQ - What to do when Perl modules aren't in their normal locations

Perl modules FAQ: I need to use a Perl module, but it isn't installed in the standard/default location, what can I do?

When you have root access to a Unix server, it's pretty easy to install Perl modules in their proper locations, and forget about them. But if you don't have root access and you need to install your Perl modules in non-standard directories, how will you get your programs to find your modules?

In this article we'll demonstrate how to use the use lib statement in your Perl programs to include the non-standard location of your Perl modules into Perl's @INC search list.

Perl modules - use and require examples (with root access)

If you're lucky enough to have root access to your Unix server, it's easy to install Perl modules into their default locations. Once they're installed in their default locations, you just include the modules into your Perl/CGI programs with a "use" or "require" statement like this:

use "LWP.pm";

or this:

require "LWP.pm";

Include Perl modules when you don't have root access ...

If you don't have access to the root password on your Unix server, or you're not allowed to add Perl modules to the Perl installation directories, what can you do? (Note: This problem usually arises when you're renting web space on somebody else's web server, and they don't have the module installed that you need -- a fairly common occurrence.)

In cases like this, the thing to do is to install the Perl module yourself into a directory where you do have write permission. For instance, if my name is George, and my HOME directory is /home/george, I might install my Perl modules into a directory named /home/george/modules. If you follow the installation instructions for Perl modules, this is very easy to do.

Assuming that goes okay and you now have the module installed in /home/george/modules, how do you get your Perl/CGI programs to find the module? Fortunately, that too is easy. All you have to do is modify your Perl/CGI program slightly to tell the program where else it should look for modules.

For instance, if the people that host my web site didn't have the CGI.pm module available, I'd install it in /home/george/modules. Then I'd modify my Perl/CGI program to find the module by adding this line near the top of my Perl programs:

use lib '/home/george/modules';

This simple line of code tells your Perl program to add this directory to it's @INC search directory. @INC contains the list of directories Perl searches when looking for modules. The use lib command is the easiest way I know to modify @INC.

Once you've made this change, you can use your normal "use" or "require" statements later in your program (just like you normally would).

How to include Perl modules - A simple example program

Listing 1 contains a small demo program you can use to test this process. When you run this program from the Unix command line, it (1) uses the use lib /home/george/modules statement to modify @INC, and then (2) prints the value of @INC to standard output. (Note: Don't try to run this program by accessing it from a web browser, because it won't work as written.)

#!/usr/bin/perl

use lib "/home/george/modules";

print "\@INC is @INC\n";

Listing 1 (above): This simple demo program shows an easy way to modify Perl's @INC variable. This lets you add your custom directories to Perl's search path, allowing you to use Perl modules that aren't installed in "default" locations.

How to include Perl modules - Summary

If you don't have access to the root account on your web server, or you're not allowed to install Perl modules into the standard directories -- fear not -- you can still install Perl modules into other directories, and then access them from your programs. Just use the use lib statement to add your search directory to Perl's search path, and your problems will be solved!