The Comprehensive Perl Archive Network (CPAN) hosts Perl modules and scripts. The CPAN module provides an interface to query and install modules hosted on CPAN. These pages document the setup and usage of CPAN, with attention to common tasks and pitfalls along the way.
Perl modules used in production must be saved locally, either under version control, a package system, or software depot. Doing so ensures the modules can be installed on new systems, or rebuilt on new platforms. This supports reproducible module installs over time, as CPAN modules may change or be removed without warning.
Use CPAN::Reporter to submit module test results. Try SmokeAuto for automated module testing.
Alternatives
Other means of installing perl modules from CPAN include the following, which are not discussed in detail here.
- CPANPLUS. “CPAN++ (also referred to and pronounced as CPANPLUS) is a new and flexible method of perl module management and installation using the CPAN. It aims to be a rewrite, and in time a replacement to the current CPAN module. In addition to fixing some long-standing problems, CPAN++ includes new features, such as module uninstall.”
- PAR - Cross-Platform Packaging and Deployment tool.
- Perl Package Manager (PPM) - Included with ActiveState Perl.
- Other. Some vendors make perl modules available via other methods, such as ActiveState’s PPM, the FreeBSD ports system, or similar package software. On Mac OS X, install XCode, or use on of the various package systems available. These offer tight integration with the system in question, but may include outdated modules or use different naming conventions and filesystem layouts.
- Conversion scripts. cpan2rpm helps convert Perl modules into RedHat Package Manager (RPM) files. The resulting *.rpm packages can be installed via a local Yellowdog Updater, Modified (YUM) server. On Debian, try dh-make-perl --install --cpan Module::Name.
For example, p5-libwww is the FreeBSD port of the module distribution libwww-perl on CPAN, and LWP::UserAgent a module found in that distribution. The following commands are equivalent means to install libwww-perl via the FreeBSD ports system, yum on RedHat systems, or the cpan command included with modern versions of CPAN.
# portinstall p5-libwww
# yum -y install perl-libwww-perl
# cpan -i LWP::UserAgent
To lookup the documentation for a module, use http://search.cpan.org/perldoc/Module::Name. The documentation should also show the distribution a module belongs to, for example Data::Dumper. Other search interfaces include the CPAN Search Site or the CPAN shell search features.
perl Upgrade Bug
The first time CPAN is invoked, it will run through a set of questions, such as which CPAN mirror site to use. Following the questions, CPAN may recommend that you install Bundle::CPAN or Bundle::libnet. Avoid installing these bundles!
Older versions of CPAN have a bug whereby a new version of perl itself may be installed. To avoid this bug, install the latest version of CPAN first. Setting the FTP_PASSIVE=1 environment variable avoids another common problem where active File Transfer Protocol (FTP) connections are blocked by a local firewall.
# perl -MCPAN -e '$ENV{FTP_PASSIVE} = 1; install CPAN'
If already in the CPAN shell following the preferences questions, use:
cpan> install CPAN
For reference, the bug is that Bundle::CPAN or Bundle::libnet may list Data::Dumper as a dependency. Data::Dumper is a built-in perl module, so when old versions of CPAN lookup Data::Dumper, they find a new version of perl to install. This bug has been fixed in current versions of CPAN.
Active FTP versus Firewalls
Network problems may prevent access to CPAN mirror sites. The chief problem will be utilities set to use active FTP, which most firewalls block. Peruse Active FTP vs. Passive FTP, a Definitive Explanation for more details. I recommend enabling passive FTP by default, though this setting will need to be done for a variety of utilities CPAN might run, such as wget or Net::FTP. Alternatives include disabling the client firewall to allow active FTP connections back from the FTP server, or configuring a local FTP proxy.
Set the FTP_PASSIVE environment variable before running cpan.
# env FTP_PASSIVE=1 cpan -i Net::FTP
During the install of the libnet distribution, enable passive FTP.
…
Ah, I see you already have installed libnet before.
Do you want to modify/update your configuration (y|n) ? [no] y
…
Should all FTP connections be passive (y|n) ? [no] y
If Net::FTP is already installed, edit the libnet.cfg configuration file to use passive FTP.
$ perl -le 'for (@INC) { $_ .= "/".$ARGV[0]; print if -f }' Net/libnet.cfg
/usr/local/lib/perl5/5.8.1/Net/libnet.cfg
$ grep passive /usr/local/lib/perl5/5.8.1/Net/libnet.cfg
'ftp_int_passive' => 1,
If Net::FTP does not work, or certain utilities take too long to time out, consider the following options.
- Disable Net::FTP.
- Disable utilities that do not work
If Net::FTP does not work, try adding the following line to the CPAN/Config.pm preferences file. More information on dontload_hash posted to the perl.perl5.porters newsgroup. Also consider installing LWP::UserAgent, which is more capable than Net::FTP.
'dontload_hash' => { 'Net::FTP' => 1 },
To reconfigure CPAN to not call certain utilities, replace the path to the utility with a single space.
$ grep ncftp ~/.cpan/CPAN/MyConfig.pm
'ncftp' => q[ ],
'ncftpget' => q[ ],
Preferences Questions
CPAN will ask for preferences settings any time the Config.pm preferences file does not exist or is out of date. The default choice should be acceptable for most.
- CPAN build and cache directory? [/root/.cpan]
- Policy on building prerequisites (follow, ask or ignore)? [ask]
- Where is your * program? [*]
- Parameters for the 'make install' command?
- Now we need to know where your favorite CPAN sites are located.
I use /var/spool/cpan, as the root filesystem tends to be small on my systems, and the spool area makes more sense to me.
Leave this setting set to ask when upgrading CPAN the first time, to prevent dependency lookups automatically installing the latest stable perl. With ask set, one can say no to queries that ask to install Bundle::CPAN, Bundle::libnet, or Data::Dumper until the latest version of CPAN is installed.
This series of questions lets one configure (or disable) paths to various utilities CPAN may use to download or unpack modules. It is safe to leave entries blank, as long as CPAN is left with at least one working program that can download modules and another to expand them.
To disable a particular utility, use a single space instead of a file path.
Set this option to include UNINST=1 if installing as root. This properly cleans out files from older versions of a module being installed. For user-specific setup, I never set the UNINST option, to avoid remove warnings of unremovable system files.
Choose several CPAN mirror sites. Use traceroute or bandwidth testing tools to determine which mirrors are best for your system. Or, mirror CPAN to a local system.
The mirrors list may need to be updated periodically, if a previous mirror site stops hosting CPAN. Symptoms of this will be slow downloads as CPAN fails though the mirror list.
Reconfiguring CPAN
To alter the CPAN preferences, either edit the Config.pm configuration file manually, or use the following command in the CPAN shell.
cpan> o conf init
The init configuration option runs through all the configuration questions, which may be time consuming. For example, other o conf commands can be used to list, remove, and add mirror sites, and then to save the changes to disk.
cpan> o conf urllist
urllist
ftp://ftp.kernel.org/pub/CPAN/
Type 'o conf' to view configuration edit options
cpan> o conf urllist shift
cpan> o conf urllist push ftp://ftp-mirror.internap.com/pub/CPAN/
cpan> o conf urllist
urllist
ftp://ftp-mirror.internap.com/pub/CPAN/
Type 'o conf' to view configuration edit options
cpan> o conf commit
commit: wrote /usr/local/lib/perl5/5.6.1/CPAN/Config.pm
To manually edit the existing configuration file, either open the user-specific ~/.cpan/CPAN/MyConfig.pm directly, or locate the system-wide configuration file (stored somewhere under the perl @INC path list) to edit with the following command.
$ perl -le 'for (@INC) { $_ .= $ARGV[0]; print if -f }' /CPAN/Config.pm
/System/Library/Perl/CPAN/Config.pm
Usage Tips
Once the latest version of CPAN has been installed, it is safe to install Bundle::CPAN (as older versions of CPAN would attempt to upgrade perl itself). If already in the CPAN shell, run reload cpan first.
cpan> reload cpan
…
cpan> install Bundle::CPAN
The following sections outline various uses and caveats with CPAN.
Invocation
The latest version of CPAN should install a cpan command somewhere on the system, which is easier to use than the traditional means of calling CPAN. With an up to date version of CPAN, the following sets of commands are equivalent. Hereafter, the shorter cpan method will be used.
# enter the CPAN shell
# perl -MCPAN -e shell
# cpan
# install the Acme::Bleach module
# perl -MCPAN -e install Acme::Bleach
# cpan -i Acme::Bleach
Depending on the shell in question, one may need to issue the hash -r or rehash command to make the new cpan command appear in the search path after the latest CPAN is installed. Consult your shell’s documentation for more information on whether this is required.
autobundle
The CPAN autobundle can be used to ease perl upgrades, by creating a special bundle containing all the installed modules of the current version of perl. This bundle can then be installed once the new version of perl is installed.
cpan> autobundle
…
Wrote bundle file
/var/spool/cpan/Bundle/Snapshot_2003_10_01_00.pm
cpan> quit
# upgrade perl here …
# cpan
cpan> install Bundle::Snapshot_2003_10_01_00
Autobundle appears to install the modules in alphabetical order; setting the prerequisites_policy policy to ask should help. Multiple install runs may be needed to install everything properly. Module build failures will lead to much recursion on the part of CPAN.
Old Modules
Some modules found by CPAN are out of date, and will not compile. An updated module may be available on CPAN, just not linked to as “current” by CPAN. Modules known to have this problem include the following. The links below should point to the current version of the modules.
Mac OS X
Problems with CPAN on Mac OS X.
Manual Build
On occasion one may need to manually build or test a module, or consult the module directory to read the documentation on any special needs the module may have. This can be done with the CPAN shell look command.
cpan> look Net::SSLeay
…
Working directory is /var/spool/cpan/build/Net_SSLeay.pm-1.25
# exit
cpan>
sudo
If CPAN is installed in your home directory, the system-wide cpan may cause problems when run via sudo(8), as by default sudo will invoke CPAN using the ~/.cpan/CPAN/MyConfig.pm configuration, but as root, which causes no end of trouble. To avoid this problem, reset the HOME environment variable with the -H option to sudo when invoking CPAN.
$ sudo -H cpan
Uninstalling
CPAN itself offers no uninstall method. Several of the alternatives to CPAN do, such as CPANPLUS or vendor package/port systems. If the module has been fully installed along with a .packlist file for the module, the ExtUtils::Packlist perl module documentation includes code for a modrm command to cleanly remove an installed module.
Modules built with other tools, such as Module::Build, may not write out a .packlist file for use by ExtUtils::Packlist.
Upgrading
How to upgrade all the modules on the system like apt-get is actually documented in the CPAN manual; however, the question comes up often enough that I answer it here as well.
# install everything that is outdated on my disk:
# perl -MCPAN -e 'CPAN::Shell->install(CPAN::Shell->r)'
Problems with this include new versions of modules that may break old module behavior, or various modules that cannot be upgraded due to build failures or system incompatibilities. Best to subject a test system to this sort of mass module upgrade before attempting it on a production system.
Debugging Module Build Problems
See the Debugging CPAN Build Problems guide for more information.
Using CPAN with a non-root account
Notes on using CPAN with a non-root account, or installing Perl modules to directories besides the default system areas, such as a software depot or under $HOME. Consider also local::lib to bootsrap custom Perl module installation directories.
Questions or comments about this page? Current ruminations available on my blog.
$Id: index.xml,v 1.46 2007/12/11 03:04:58 jmates Exp $