How you configure and manage your Perl installation depends on your operating system, Perl version, and your work environment. A team building a publicly deployed application will often need a different configuration than your personal workstation or a shared web hosting environment.

This article covers the ins and outs of installing perl modules and configuring your installation.


The Comprehensive Perl Archive Network (CPAN) is a collection of freely available Perl modules contributed by thousands of authors. It is mirrored on hundreds of servers around the world. If you are trying to accomplish a common task in Perl, it is likely that someone else has already made a module which does most of the work for you. You simply have to find it and install it.


Packages on the CPAN are called distributions, which are "tarballs" (.tar.gz archives) containing Perl modules and scripts, as well as build tools, documentation, tests, and license information. A distribution may contain just one module, or a set of modules.

A distribution may require modules from other distributions, either as part of its implementation or to extend another module's functionality. These are referred to as dependencies. Rather than rewriting code, module authors can simply reuse existing code from other modules. This helps reduce complexity and bugs (for you and the module authors) by organizing code into well-tested, reusable components. However, module A might depend on B, which depends on C, D, and E. This makes installation slightly more complicated, but there are tools to deal with that.

The Standard Build Process

A distribution on the CPAN comes with a Build.PL file (or Makefile.PL), which knows how to examine your system, check whether dependencies are satisfied, and generate a build file. The generated Build file (or Makefile) can then be used to build, test, and install the distribution's modules, scripts, documentation, and data.

Note: you will usually not need to go through this process manually (we'll get to that in the section on CPAN clients), but knowing how it all works will help when things go wrong.

If you download a distribution tarball from the CPAN and unpack it (tar -xzvf Foo-0.01.tar.gz, then cd Foo-0.01), the typical installation process is:

  perl Build.PL
  ./Build test
  ./Build install

Note: on Windows, use the backslash (.\Build) instead.

Or, if you only have a Makefile.PL:

  perl Makefile.PL
  make test
  make install

The 4 Steps

perl Build.PL

This checks for dependencies, compatibility, and will print error messages if anything is wrong or missing. It may also print messages about optional dependencies (which would enable extra features for the module.) If something goes wrong at this point, you need to resolve the problem before continuing. In severe cases, the Build.PL script will refuse to create a Build file.


This step compiles any XS-based extension modules and does whatever heavy lifting is needed. In simple cases, it just copies some files into the ./blib/ "staging area" directory. When this step is complete, the files in ./blib/ are exactly what will be installed on your system.

./Build test

This is the all-important step where we find out if the code actually works. (You did want the code to work, right?) This will run all of the *.t files in the distribution's t/ directory. Testing verifies that the code works on your system and works as the author intended.

Most distributions will at least do a use Foo test to check for syntax errors or crippling problems. Many will have a full battery of tests which exercise the module's functionality. Some even have extra tests, which can optionally run more exhaustive tests, or test code which accesses a database, network connection, modem, etc.

For more info, see Test::Harness and the distribution's README file.

./Build install

Once the tests pass, you're ready to install the module to its permanent home. This copies the files from the ./blib/ staging area into appropriate places — .pm files go in @INC, scripts in $PATH, and so on. Arguments given to perl Build.PL step (such as --installdirs=site) and settings from when your perl was built will control the exact locations.

You may need to run `sudo ./Build install` or set appropriate write permissions for the installation path.

For further reading, see the perldoc for perlmod, perlmodinstall, and perlmodlib.

External Dependencies

Some Perl modules depend on external libraries (such as the C libraries expat or libxml) which need to be installed before the module can be compiled. In some cases, the module will depend on a package in the Alien:: namespace — a special kind of distribution designed to automatically fulfill the dependency for you using the standard build process described above. But if you run the perl Build.PL step and get a message like "missing such-and-such library", you'll have to handle it yourself.

For debian/ubuntu, you can usually find and install the library in Synaptic (or aptitude). Look for a package named "lib$foo-dev", or "$foo-dev". Redhat systems would call it "lib$foo-devel". OS X users can use MacPorts or Fink. If you don't have prebuilt packages available for the library, you need to find the source, download it, run configure, make, and so on. Don't panic. The perl module's README or INSTALL file should have details about this sort of thing when necessary.

CPAN Clients

The four-step process is pretty simple, but actually has some hidden steps in the beginning where you find and download the distribution, unpack it, and cd into its directory. This can get especially tedious when the distribution has a dependency, which has a dependency, which has a dependency, and so on. This sounds like a job for the computer! A CPAN client is a program which knows how to fetch distributions from the CPAN and figure out all of their dependencies. Then it runs our 4-step process to build, test, and install everything while you check your mail and drink coffee.


The cpan client comes with the core Perl distribution and is probably already installed on your system. But, it probably needs an upgrade if you are running an old Perl or are using the perl that came with your system. If you have installed perl 5.10 or newer, the client is ready to go with minimal configuration.

If you have an old cpan client, it may be easiest to download a tarball from the CPAN, unpack that, and go through the 4-step process. Upgrading from an old client can be painless if it is configured correctly and nearly impossible otherwise.

Client Configuration

The cpan program has an interactive shell for configuration, searching, and other functionality. When you run `cpan` at your terminal with no extra arguments, it starts in this interactive mode.

The first time you run the client, it starts by explaining its purpose and prompting you for configuration:

  $ cpan
  CPAN is the world-wide archive of perl resources. It ...

  If you prefer to enter a dialog instead, you can answer 'no' ...
  Would you like me to configure as much as possible automatically? [yes]

(Note that I have trimmed the output with '...' to keep this page short.)

When you hit 'Enter' here, the client will go through a series of checks and figure out how to operate on your system.

  Autoconfigured everything but 'urllist'.
  Please call 'o conf init urllist' to configure your CPAN server(s) now!

  commit: wrote '/home/yournamehere/CPAN/'

  cpan shell -- CPAN exploration and modules installation (v1.9402)
  Enter 'h' for help.


Now you're at the interactive prompt. Note that it prints out the location of your new config file. But you still need to select a mirror of the CPAN. You can simply step through the prompts and then pick a mirror.

  cpan[1]> o conf init urllist

  Now we need to know where your favorite CPAN sites are located.

  First, pick a nearby continent and country ...
  (6) North America
  Select your continent (or several nearby continents) [] 6

  (4) United States
  Select your country (or several nearby countries) [] 4

  38 more items, hit RETURN to show them
  Select as many URLs as you like (by number),
  put them on one line, separated by blanks, hyphenated ranges allowed
   e.g. '1 4 5' or '7 1-4 8' [] 37

  Enter another URL or RETURN to quit: []
  New urllist

  Please remember to call 'o conf commit' to make the config permanent!

We're back at the prompt again, but the client did not write the config file!

  cpan[2]> o conf commit
  commit: wrote '/home/yournamehere/CPAN/'

Now you probably need to change a couple of important settings before trying to build anything. If your perl is installed in /usr/local, your non-root user does not have permission to write files there. So, you can configure the client to be root only when installing. (You won't need this setting if you installed a "personal" perl in your home directory.)

  cpan[3]> o conf make_install_make_command 'sudo /usr/bin/make'
    make_install_make_command [sudo /usr/bin/make]
  Please use 'o conf commit' to make the config permanent!

  cpan[4]> o conf mbuild_install_build_command 'sudo ./Build'
    mbuild_install_build_command [sudo ./Build]
  Please use 'o conf commit' to make the config permanent!

Note that it is still pestering us about this 'commit' business. Well, we can just make that automatic, so that whenever we change the configuration it immediately writes it to the config file.

  cpan[5]> o conf auto_commit 1
    auto_commit        [1]
  commit: wrote '/usr/local/share/perl/5.8.8/CPAN/'

Another important setting is whether or not to prompt you about dependencies. It's best if the client just installs whatever a module needs. This way, when you come back from reading your mail it isn't sitting there waiting for you to answer "should I install some stuff so this will actually work?".

  cpan[6]> o conf prerequisites_policy follow
    prerequisites_policy [follow]
  commit: wrote '/usr/local/share/perl/5.8.8/CPAN/'

Finally, we can use the client to install a module.

  cpan[7]> install Foo
  Fetching with LWP: ...

Everyday Usage

To install one or more modules from the CPAN, you can simply invoke the client with the names of the modules you want installed:

  $ cpan Foo Bar Baz


Upgrade the Tools

Code on the CPAN changes every day, but huge improvements to how the build tools work have happened since perl 5.8.8 came out. If you're running an older perl, you should at least upgrade your CPAN, ExtUtils::MakeMaker and Module::Build to the latest versions from the CPAN. This will ensure that everything works as-intended with current CPAN distributions.

You might notice that CPAN informs you at startup when a new version is available. When you see this, it is time to upgrade. You can upgrade the CPAN client by simply running 'install CPAN' from inside the cpan shell.

Install Bundle::CPAN

Installing the Bundle::CPAN distribution will add a lot of nice functionality to

Don't run cpan as root!

Use sudo only to install. It's possible for a test to make a mistake which deletes your entire filesystem (and maybe didn't affect the author.) This sort of thing is rare, but you don't want to risk it, so only use sudo for the installation phase — when you actually need root permissions to install the code. If you have previously run cpan as root or as sudo cpan, you might need to reconfigure or chown -R your ~/.cpan/ directory so you can use it again.

prefer_installer MB

If you upgraded from an older, make sure your prefer_installer is set to 'MB'. This means that when a distribution has both Makefile.PL and Build.PL build tools that the client will use the Build.PL-based process. When a distribution has both, the Makefile.PL is actually only a wrapper on Build.PL to try to help the new system be compatible with old clients. Unfortunately, a series of old versions would default this to 'MM' and if you had one of those once, it is still set that way. The default in a freshly installed is 'MB'.

  cpan[1]> o conf prefer_installer MB
    prefer_installer   [MB]

o conf init whatever

You can run 'o conf' at the interactive shell (or read the config file) to see all of your client's settings. Running 'o conf init' would take you through the whole configuration process again, but 'o conf init whatever' will give you an explanation of the whatever setting and show you the options for it. Unfortunately, it doesn't tell you the factory default (the prompt default is now the current value from your config file.) If you want to get the factory defaults from your newly installed version, rename your config file and then run through the init process again.


The CPAN::Mini module makes it possible to have a small local mirror of the CPAN, updated to have only the latest tarball of every module. This is nice to have on your laptop if you're working on an airplane or with spotty internet access. It also saves downloading time if you are installing modules on multiple computers in your network.


The cpanp client (in the CPANPLUS distribution) is a newer option which offers more configurable and advanced functionality over the venerable

Installing One or More Perls

If you have a large or important codebase, it's best to maintain your own perl installation rather than using whatever came with the system. An OS distribution (like RedHat, Debian, or OS X) often has made subtle changes to their 'perl' which may not be best for your uses. You should keep the system perl as-is because scripts that came with the system are tested only against the vendor's version. Install your own /usr/local/bin/perl, or even put it under a numbered 'prefix' such as /usr/local/perl-5.10.1/.

To install perl under a custom 'prefix', just run Configure with e.g. -Dprefix=/usr/local/perl-5.10.1/. See the installation howto for details.

Many CPAN developers keep a few different versions of perl on their machine for testing purposes. If you are writing C-based extensions, you'll want to build a debugging-enabled perl for running with gdb.

When your team is preparing to upgrade your product to a new perl version, it is good to be able to test the new version alongside the old one. Then you can just change the environment's $PATH to point at the new perl when everything is ready for the switch. It is much simpler to manage upgrades if you have a /usr/local/perl-5.8.8/bin/perl and /usr/local/perl-5.10.1/bin/perl, even for multiple codebases on different schedules.

Module Management with local::lib

The local::lib module is a way to create and use a tree of modules outside of perl's builtin @INC paths. It does this by setting some variables in your environment to adjust the installation targets and sets PERL5LIB accordingly. This can be setup in your shell to make cpan install code under your home directory. It is very useful for shared hosting environments where you only have write access in your home directory, or other cases where you want to keep code from the CPAN in a specific place.

If you want to build a tree under ~/.perl (a hidden path under your home directory), download the tarball for local::lib, unpack it, and run its bootstrap setup as follows:

  $ perl Makefile.PL --bootstrap=~/.perl
  $ make test && make install

  $ echo 'eval $(perl -I$HOME/.perl/lib/perl5 -Mlocal::lib=$HOME/.perl)' >> ~/.bashrc

This last command adds the environment setup to your ~/.bashrc (which is run whenever you login.) You need to restart your shell (or source ~/.bashrc) to get your shell ready to run cpan with the new environment.

To see how this works, examine the pieces. The eval is a bash construct which is similar to Perl's eval($string), and the $() construct is the bash capture-output operator (like Perl's qx() or backticks). So this runs local::lib's import() method (see perlrun for -I and -M), which prints some bash code. If you run just the perl part, you can see how the sausage is made:

  $ perl -I$HOME/.perl/lib/perl5 -Mlocal::lib=$HOME/.perl/lib/perl5
  export MODULEBUILDRC="/home/you/.perl/lib/perl5/.modulebuildrc"
  export PERL_MM_OPT="INSTALL_BASE=/home/you/.perl/lib/perl5"
  export PERL5LIB="/home/you/.perl/lib/perl5/lib/perl5:$PERL5LIB"
  export PATH="/home/you/.perl/lib/perl5/bin:$PATH"

The first two variables are for Module::Build and ExtUtils::MakeMaker — this makes the installers target this tree. The PERL5LIB variable tells perl where to find the modules and the PATH variables tells your shell where to find the scripts. You could setup these pieces manually, or might want to set just the PERL5LIB variable in e.g. your Apache configs.

For more details and options, see the local::lib documentation.

Further Reading

The Perl module system and build tools are very flexible. Your situation can usually be handled simply by adjusting the configuration or environment.

Common Problems

Most of the problems people have using the CPAN comes down to configuring or upgrading their CPAN client. Either the client was pre-configured, or was never properly configured. It is usually something very simple, but you could be starting in one of thousands of possible situations. If in doubt, clean off the slate and start fresh.

Rusty Old Tools

If you cannot run on a new perl (why not?), you must upgrade, install Module::Build, install ExtUtils::MakeMaker, install Bundle::CPAN, and you may need to reconfigure your CPAN client from a clean slate (o conf init). Various older CPAN clients will run into snags trying to self-upgrade (needing to be configured, restarted, upgraded, restarted, reconfigured, restarted, configured, etc.) Just scrap the old client and get a fresh tarball.

Crufty Old Config

If your CPAN client does not prompt you for configuration when you first run it, you might need to delete whatever configuration it is using. When you run 'o conf' from the interactive shell, it prints "$CPAN::Config options from ''". Remove that file and try again.


You might see a message like 'Cannot write some file ... permission denied' in the build output. When this happens, you have to track down which directories need which permissions and may need to use 'sudo' to fix it, setup your client to install elsewhere, or use local::lib.

Failing Tests

If you have upgraded and properly configured your CPAN client, but are still having trouble installing a module, it might be a bug in the module (or one of its dependencies.) Carefully read the output from the build process, find out which module is building when it fails, and isolate the problem.

You may need to run the 'look' command from the interactive shell to drill-down into the module and manually step through the build process. You'll either find something wrong with your system or a bug in the module (or its tests.) When you find a bug in a distribution on the CPAN, report it to the distribution author so it can be fixed. Often, the module's author is using a different platform and has not experienced the bug.