Life with CPAN

perl Upgrade Bug | Active FTP versus Firewalls | Preferences Questions | Reconfiguring CPAN | Usage Tips | Debugging Module Build Problems | Using CPAN with a non-root account

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.


Other means of installing perl modules from CPAN include the following, which are not discussed in detail here.

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
$ 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.

Preferences Questions

CPAN will ask for preferences settings any time the preferences file does not exist or is out of date. The default choice should be acceptable for most.

Reconfiguring CPAN

To alter the CPAN preferences, either edit the 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
Type 'o conf' to view configuration edit options

cpan> o conf urllist shift

cpan> o conf urllist push

cpan> o conf urllist
Type 'o conf' to view configuration edit options

cpan> o conf commit
commit: wrote /usr/local/lib/perl5/5.6.1/CPAN/

To manually edit the existing configuration file, either open the user-specific ~/.cpan/CPAN/ 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/

Usage Tips

Invocation | autobundle | Old Modules | Mac OS X | Manual Build | sudo | Uninstalling | Upgrading

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.


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.


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

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/
# exit


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/ 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


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.


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.