Skip to content

Install your own Perl Modules

Installing your own Local Perl Modules

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> h                         <-- Shows help 
cpan> m Module::Name            <-- This will search for a module by module name
cpan> install Acme::Time::Baby  <-- This will install a module

This is how to upgrade your cpan:

cpan> install Bundle::CPAN      <-- Update your CPAN
cpan> reload cpan

The first time you invoke cpan it will need to setup its configuration. Below is a transcript of a typical initial use where it sets up configuration:

~/$ perl -MCPAN -e shell

Configuration will be written to:

/shared/homes/xxxxxx/.cpan/CPAN/MyConfig.pm

CPAN.pm 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')
 [local::lib]

New urllist
  http://www.mirrorservice.org/sites/cpan.perl.org/CPAN/
  http://ftp.sunet.se/pub/lang/perl/CPAN/
  http://mirrors.xservers.ro/CPAN/

Autoconfiguration complete.

PERL_MB_OPT="--install_base \"/shared/homes/xxxxxx/perl5\""; export PERL_MB_OPT;
PERL_MM_OPT="INSTALL_BASE=/shared/homes/xxxxxx/perl5"; export PERL_MM_OPT;

Would you like me to append that to /shared/homes/xxxxxx/.bashrc now? [yes]

commit: wrote '/shared/homes/xxxxxx/.cpan/CPAN/MyConfig.pm'

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.

cpan[1]>

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 /shared/homes/xxxxxx/.cpan/CPAN/MyConfig.pm:
    commit             [Commit changes to disk]
    defaults           [Reload defaults from disk]
    auto_commit        [0]
    build_dir          [/shared/homes/xxxxxx/.cpan/build]
... lots more ....
    wget               [/bin/wget]
    yaml_load_code     [0]
    yaml_module        [YAML]
cpan[2]>

Here is how to reconfigure specific variables:

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

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

Using CPANMINUS (cpanm)

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

Installation: 

$ curl -L https://cpanmin.us | perl - App::cpanminus 
  % 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 http://www.cpan.org/authors/id/M/MI/MIYAGAWA/App-cpanminus-1.7024.tar.gz ... 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.

Installing Modules under Perl Brew

This should have aleady been done when you installed perlbrew:

$ perlbrew install-cpanm
$

You should be using the cpanm under perlbrew: 

$ which cpanm
~/perl5/perlbrew/bin/cpanm

Switch to your installed perl e.g. 5.34.0 

$ perlbrew switch perl-5.34.0

Now you can install cpan modules using cpanm.

Useful Things

Where Perl searches for Modules

This is a nice post on stackoverflow.com 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?)”

References

cpanminus:
http://search.cpan.org/~miyagawa/App-cpanminus-1.7024/lib/App/cpanminus.pm
http://search.cpan.org/~miyagawa/App-cpanminus-1.7024/bin/cpanm

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.