Life with CPAN

Interfaces to CPAN | Usage Tips | Debugging Build Problems | Using CPAN with a non-root account | Operating System Particulars

The Comprehensive Perl Archive Network (CPAN) hosts Perl distributions. The CPAN module provides an interface to query and install modules hosted on CPAN. Other interfaces are available, such as the CPAN webpage, or App::cpanminus.

Perl distributions (example: libnet) contain one or more module files, plus other metadata files, unit tests, and more. The module files are often arranged in a hierarchy, though this arrangement is left to the author: the module Acme::Foo and the module Acme::Foo::Bar could belong to two different distributions that have nothing to do with one another. Various conventions keep the Perl authors in line, though there is no formal organization.

Perl modules (example: Net::FTP, part of the libnet distribution) are usually pure Perl. Some modules however contain XS code; these require a C development environment to compile, plus various C libraries. Check the vendor ports or package system, or compile by hand, depending. Some modules have additional requirements. DBD::Pg requires both the Postgres development environment to compile against and a Postgres database to connect to. Perl module names are Case Sensitive.

perl searches @INC for modules. Net::FTP is stored as Net/ on a Unix filesystem, and the first matching entry in @INC will be used. @INC can be adjusted in a variety of ways.

$ perl -E 'say for grep { -f "$_/Net/" } @INC'
$ file /System/Library/Perl/5.10.0/Net/
/System/Library/Perl/5.10.0/Net/ Perl5 module source text

Interfaces to CPAN

Various software exists to install Perl distributions from CPAN. CPAN is the traditional interface; systems with limited resources will benefit from the simplicity of App::cpanminus. Perl modules are ideally organized into a custom library directory; local::lib provides an easy method of creating arbitrary library directories for any user.

Various software exists to help organize or package Perl modules for reuse elsewhere. These can be used in conjunction with an installer:


Many vendors offer alternate methods of installing Perl modules, usually by converting Perl distributions into a custom ports or package system. These methods are usually not portable beyond the operating system or port or package environment involved, though may suit sites heavily invested in that port or package system:

Note the different naming conventions used by different installation systems. The following commands are equivalent means to install libwww-perl on Debian, via the FreeBSD ports system, yum on RedHat systems:

# apt-get install libwww-perl
# portinstall p5-libwww
# yum -y install perl-libwww-perl

The same Perl distribution has a distinct name in each different package system! When requesting help, note whether the problem is with a Perl module or distribution, or with a vendor port or package of such. A Perl module that cannot be found on CPAN may belong to some vendor application, and help requested from that vendor, not the Perl community.

A site may only use vendor port or package installed perl distributions, or may end up using a mix of vendor supplied data and Perl modules installed to various directories on a system. While individuals can cobble together whatever works for them, larger sites will benefit from increased formalism in how software is installed and maintained.

Automated Testing & Feedback

Use CPAN::Reporter to submit module test results. Try SmokeAuto for automated module testing.

Usage Tips

Consult the usage tips documentation for more information, such as how to perform case sensitive searches, install specific module versions, and more.

How to uninstall Perl modules comes up fairly often. Not sure why, as there are better things to waste time on, and little if nothing to gain from removing modules. (I have similar thoughts on “looking to find what Perl modules are installed on a system” (run perldoc -q installed for some ideas)—never seen a use for such an audit. Perhaps on poorly maintained systems that have who know what installed who knows where?

Debugging 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 a personal module tree under $HOME. Consider also local::lib to bootstrap custom Perl module installation directories.

Operating System Particulars

Problems with CPAN on Mac OS X. On Windows, consider Strawberry Perl.