Installing your own Local Perl or CPAN Library on the Cluster

There are three methods to install perl modules: CPAN, CPANMINUS and CPANPLUS.

CPAN (cpan) is the original, basic method for installing perl modules. It comes with Perl, so you already have it and it has the most features. However it has a lot of configuration options that you need to customize when its first run.

CPANMINUS (cpanm) is a zero-configuration module installer that does the right thing for most users most of the time. It doesn't come with Perl, but it's easy to install. It integrates easily with local::lib.

CPANPLUS (cpanp) is a CPAN API that Perl programs can use, but it does have a shell that can be used to query, download and install modules. There are apparently no advantages to using this over CPANMINUS.

Aside: Unlike the bash shell, history and command completion will not work by default. To enable them you need to install the perl modules: Term::ReadKey and either of Term::ReadLine::Perl or Term::ReadLine::Gnu as shown below (using cpanm):

$ cpanm Term::ReadKey
$ cpanm Term::ReadLine::Perl

Using CPAN (cpan)

Start it using either of the two following commands: perl -MCPAN -e shell which starts the CPAN shell, or just type cpan.

$ cpan
cpan> m Module::Name        <-- This will search for a module
cpan> i Acme::Time::Baby    <-- This will install a module (you can also leave out the "i")

Transcript of initial use where it sets up configuration:

~/$ perl -MCPAN -e shell

Configuration will be written to:

/home/mlake/.cpan/CPAN/ requires configuration, but most of it can be done automatically.
If you answer 'no' below, you will enter an interactive dialog for each
configuration option instead.

Would you like to configure as much as possible automatically? [yes] 

Warning: You do not have write permission for Perl library directories.

To install modules, you need to configure a local Perl library directory or
escalate your privileges.  CPAN can help you by bootstrapping the local::lib
module or by configuring itself to use 'sudo' (if available).  You may also
resolve this problem manually if you need to customize your setup.

What approach do you want?  (Choose 'local::lib', 'sudo' or 'manual')

New urllist

Autoconfiguration complete.

PERL_MB_OPT="--install_base \"/home/mlake/perl5\""; export PERL_MB_OPT;
PERL_MM_OPT="INSTALL_BASE=/home/mlake/perl5"; export PERL_MM_OPT;

Would you like me to append that to /home/mlake/.bashrc now? [yes] 

commit: wrote '/home/mlake/.cpan/CPAN/'

You can re-run configuration any time with 'o conf init' in the CPAN shell
Terminal does not support AddHistory.

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


Note: This will have set some variables to be exported in .bashrc

You can view this configuration with 'o conf'. Here is an example from my own directory.

cpan[1]> o conf
$CPAN::Config options from /home/mlake/.cpan/CPAN/
    commit             [Commit changes to disk]
    defaults           [Reload defaults from disk]
    auto_commit        [0]
    build_dir          [/home/mlake/.cpan/build]
... lots more ....
    wget               [/bin/wget]
    yaml_load_code     [0]
    yaml_module        [YAML]

Here is how to reconfigure specific variables:

o conf make_arg -I/shared/homes/mlake/perl5
o conf make_install_arg -I/shared/homes/mlake/perl5
o conf commit

I find it easier to just manually edit my .cpan/CPAN/

Using CPANMINUS (cpamm)

cpanm is:

  • easier to use when things go right
  • no configuration required
  • can skip tests on install (eg for DBD::MYSQL) examples: cpanm -n DBD::mysql
  • can uninstall


wget -O - | perl - --self-upgrade 
curl -L | perl - App::cpanminus 

$ curl -L | perl - --self-upgrade
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   314    0   314    0     0    788      0 --:--:-- --:--:-- --:--:--   788
100  294k  100  294k    0     0   120k      0  0:00:02  0:00:02 --:--:--  162k
Working on App::cpanminus
Fetching ... OK
Configuring App-cpanminus-1.7024 ... OK
Building and testing App-cpanminus-1.7024 ... OK
Successfully installed App-cpanminus-1.7024
1 distribution installed

cpanminus at a boot time checks whether you have configured local::lib, or have the permission to install modules to the site_perl directory. If neither, it automatically sets up local::lib compatible installation path in a perl5 directory under your home directory.

Using Perl Brew

First we need to "initialise" a local directory for our perl brews:

$ perlbrew init
perlbrew root (~/perl5/perlbrew) is initialized.
Append the following piece of code to the end of your ~/.bash_profile and start a
new shell, perlbrew should be up and fully functional from there:

    source ~/perl5/perlbrew/etc/bashrc

Simply run `perlbrew` for usage details.
Happy brewing!

I edited my .bash_profile and included that line. Remember to logout and login again to invoke that change in your .bash_profile.

Let's see what versions of Perl are available:

$ perlbrew available

Let's install version 5.20.1

$ perlbrew install perl-5.20.1
Fetching perl 5.20.1 as /home/mlake/perl5/perlbrew/dists/perl-5.20.1.tar.bz2
Download to /home/mlake/perl5/perlbrew/dists/perl-5.20.1.tar.bz2
Installing /home/mlake/perl5/perlbrew/build/perl-5.20.1 into ~/perl5/perlbrew/perls/perl-5.20.1

This could take a while. You can run the following command on another shell to track the status:
tail -f ~/perl5/perlbrew/build.perl-5.20.1.log
an hour later ....

perl-5.20.1 is successfully installed.

It's installed. However we will need to install cpanm to manage our modules. Perlbrew comes with an option to do that for us.

$ perlbrew install-cpanm
  cpanm is installed to

Now lets switch to our just installed perl 5.20.1 and have a look at our environment to see what changes have been made.

$ perlbrew switch perl-5.20.1

$ env | grep PERL

$ which perl

Now you can install cpan modules using cpanm.

The perlbrew command "lib" might be useful.

perlbrew lib list
perlbrew lib create <lib-name>
perlbrew lib delete <lib-name>

Type perlbrew help lib for detailed information.

Useful Things

Set a useful Bash Prompt

In your .bashrc set your PS1 variable like this:

PS1="`perlbrew list | grep \* | sed s/'* '//`$ "

Now your bash prompt will show the version of Perl that is in effect.


Where Perl searches for Modules

This is a nice post on which explains how Perl finds Perl modules: How is Perl's @INC constructed
Search on Google for: "How is Perl's @INC constructed? (aka What are all the ways of affecting where Perl modules are searched for?)"

Alternatives to Perl Brew



How To Install CPAN Modules

References for Perlbrew: and

References to local::lib

Chisel Blog: local::lib and perlbrew

perlbrew and local::lib at the same time?

Other useful links:

Keep your libraries organized

Carton - Perl module dependency manager and also see this FAQ at this site.