Perl Programming/CPAN

From Wikibooks, open books for an open world
Jump to navigation Jump to search
Previous: GUI programming Index Next: CPAN/Bitcard

CPAN[edit | edit source]

A huge collection of freely usable Perl modules, ranging from advanced mathematics to database connectivity, networking and more, can be downloaded from a network of sites called CPAN. Most or all of the software on CPAN is also available under either the Artistic License, the GPL, or both. is also the name of the Perl module that downloads and installs other Perl modules from one of the CPAN mirror sites; such installations can be done with interactive prompts, or can be fully automated.

Look for modules on CPAN

Installing modules[edit | edit source]

With ActivePerl (Windows systems)[edit | edit source]

From a command-line, type the command


This will give you a "Perl Package Manager" prompt, which allows you to download and install modules from the internet. For example, to install the Time::HiRes module, type:

search time::hires

That will give you a list of modules that match your search query. Once you know the module is available and what its exact name is, you can install the module with:

install Time::HiRes

With Perl[edit | edit source]

If you're using a normal version of Perl, the way to activate the package manager is this:

perl -MCPAN -e shell;

This will load the CPAN module, and let you search for, download, install, and manage the modules on your computer the same as PPM.

With Perl (cpanm)[edit | edit source]

The Perl module cpanm (CPAN Minus) is another alternative for installing modules from the CPAN library

cpanm can be installed and used like this on a UNIX-like system:

curl -L "" >cpanm
chmod +x cpanm
./cpanm LWP::Bundle

One must have root privileges in order to install module in the system-wide directories, however alternatives exist such as local::lib, which allows regular users to install and use Perl modules in their home folder

With Strawberry Perl (Windows systems)[edit | edit source]

Strawberry Perl also includes the CPAN module, so you can use the command above to activate the package manager.

The start menu, however, also includes a shortcut (with the name of "CPAN Client") so that you don't have to go to a command line to do so.

A number of modules are already included in Strawberry Perl, beyond what comes with a normal version of Perl, or what comes with ActivePerl, so you may wish to check, if the module you want is already installed before you start the CPAN client.

Using a module in your program[edit | edit source]

To incorporate a module into your program, use the use keyword:

use Time::HiRes;

You can supply an optional list of the functions you want to use from this module, if you're worried that some of the function names in the module are too similar to functions you're already using:

use Time::Hires qw(time gmtime);

With that done, you can simply use the supplied functions as normal. Most modules have example programs within their documentation, and the best way to start using a module is to copy and adapt one of the example programs.

Finding documentation[edit | edit source]

The documentation for each module is installed in your documentation directory when you get a new module, or you can browse documentation on and

Unix systems[edit | edit source]

On Unix systems, the documentation is usually installed as man pages in section 3p so that the command below will work:

man 3p Module::Name

perldoc Module::Name will also work.

If you want documentation that is browseable in a web browser, you can install Perldoc::Server as noted below.

Windows systems running ActivePerl[edit | edit source]

Module documentation is installed as HTML files in ActivePerl. To find those files, try looking in some of the following directories:

  • C:\Perl\html\lib
  • C:\Perl\html\site\lib

If you're having real trouble finding the HTML documentation for a module, you may be able to read the *.pm Perl file yourself for POD comments, or use the pod2html tool yourself to generate the HTML file.

Windows systems running Strawberry Perl[edit | edit source]

Strawberry Perl does not install module documentation as either manpages or html files. Instead, you can run the perldoc command to display module documentation.

perldoc Module::Name

You can also use Perldoc::Server to display module documentation, as illustrated below.

Perldoc::Server[edit | edit source]

The Perldoc::Server module (that can be installed via CPAN) will provide a local server that will display HTML files "on the fly" from Perl's documentation and the documentation for installed modules. Install it, and the command


will be in your path. Run it, and then browse to http://localhost:7375/ in your Web browser to see the documentation.

Note that the perldoc-server command must be running to provide the documentation using this method.

Contributing your own modules to CPAN[edit | edit source]

In the event that a module you need isn't available on CPAN, the usual answer is to write the module yourself and add it to CPAN. That way, nobody else needs to waste time creating the same functionality that you're already written.

See How to contribute modules to CPAN

Previous: GUI programming Index Next: CPAN/Bitcard