How to Install CPAN Modules

This document is being revised and may be incomplete or inconsistent


CPAN (Comprehensive Perl Archive Network) is a large repository of Perl modules. Standard Perl already has many CPAN libraries pre-installed.

As of Foswiki 2.0, Foswiki no longer ships with any CPAN modules. It is recommended that you use your system package manager, or if necessary, App::cpanminus to install any missing dependencies. This guide tells you how to do that.

For building the CPAN modules from sources it is assumed that you have a fully working Perl and C development environment (including a C compiler and make tool) - but you may have much easier alternatives. This is not required if you can install the libraries as packages (rpm, deb, etc.)

What Do I Need?

If you have not yet installed Foswiki: Review the SystemRequirements that is shipped with your version of Foswiki. It lists the required modules.

If Foswiki is installed and operational:
  • For Foswiki 1.1.9 or older, run bin/configure and review the contents of the Web Server Environment tab. there is a subsection "Perl modules" which lists the version of the installed modules and also the missing modules. (On oldest 1.0.x versions of Foswiki, the "CGI Setup" tab in configure lists dependencies).
  • For Foswiki 2.0, visit PerlDependencyReport, or run tools/dependencies from the command line. This will report any missing dependencies.

Which CPAN Libraries Do I Have?

To test if you have a specific CPAN modules installed, follow this easy method:

This is best explained by example:

  • To check for perl module FileHandle: perl -e 'use FileHandle; print $FileHandle::VERSION."\n"'
  • To check perl module Time::Local: perl -e 'use Time::Local; print $Time::Local::VERSION."\n"'
If you think a perl module is installed, but the system claims it can't find it, then it's worth reviewing HowFoswikiFindsPerlLibraries to help understand what is going on.

Install CPAN Modules using the package management system

If your system is one of the more popular Linux distributions then by far the easiest way to install additional CPAN modules is to use the package management system.

For distributions like RedHat, CentOS, Fedora, Mandriva, etc. most CPAN libraries are available as RPM packages. If you need a CPAN library called CPAN:CGI::Session then the naming convention normally used is perl-CGI-Session. Not all the CPAN libraries can be found on your CD/DVD or in the official distribution package repositories. But there are many additional repositories that carry nearly all the CPAN libraries.

For Debian based distributions, including Ubuntu, the naming convention is a little different. For example, the CGI::Session library is called libcgi-session-perl. The good thing with Debian is that they carry most of the CPAN libraries on the official package repositories so once you know what they are called they are just a simple apt-get away, e.g. apt-get libcgi-session-perl installs the CGI::Session module from CPAN. You can also use GUI tools such as Synaptic to find and install such modules. See InstallationOnDebian and SupportInstallationOnUbuntu for more.

HELP On Ubuntu you might find that by default CGI v3.37, 3.43 or 3.47 are installed. These versions, according to Foswiki documentation, must be avoided. One possible solution is to install libcgi-pm-perl, which currently replaces the default version by a supported one (2011-0-10). To do so, type sudo apt-get install libcgi-pm-perl from the command line or install it with your favorite package manager.

Gentoo has ebuilds for the CPAN. E.g. CGI::Session is called CGI-Session. See for an overview of Perl CPAN related ebuilds.

InstallationOnRedHat has a detailed description of which CPAN libraries are required in addition to the ones that are installed by default and the exact method how to install them. This covers RedHat, Centos and Fedora. If you have another RPM based distribution this is also a very good resource.

Install CPAN modules into your local Perl library using App::cpanminus

CPAN has evolved and the easiest way now to install CPAN modules is using the CPAN:App::cpanminus installer. It can be run with or without root privileges. When run as root it installs into the system libraries. When run without root privileges, it installs into a local perl library. For example, run here with root access, cpanm is installed into the System perl libraries, and then Archive::Zip is installed.

curl -L | perl - App::cpanminus
cpanm Archive::Zip

Setting up a private CPAN library - without admin privileges

If you don't have admin privileges and want to install required CPAN modules locally, this is how you do it. The instructions are written for Unix/Linux users, such as shared web hosting users, or users of an intranet Unix/Linux server.

This page will help you create a private CPAN library. You can put your private library anywhere; just type in the path you want to use below. Remember that the webserver user has to be able to find and read the path, though!

Enter the full path to your CPAN directory:

Now start the CPAN shell in your home directory:

$ cd ~
$ perl -MCPAN -e shell

You can just answer "no" to manual configuration, and wait for the noise to die down, or you can answer "yes" and step through the questions. You should accept the defaults for most questions, except the ones about your mirror locations.

Now type the following at the cpan> prompt (note that each line starts with o conf all others are wrapping):

TIP Tip: at any point you can use o conf to review your options and help for (limited) help. In .bashrc (or your shell's equivalent), set PERL5LIB:

export PERL5LIB=/home/foswiki/lib/CPAN/lib

Now, when you run perl -MCPAN -e shell, any modules you install will be installed to your private library directory.

Note: several people can all share the same CPAN library; they can all follow the instructions above.

Note: If you do not get the cpan> prompt and instead get error messages about permissions failures creating /root/.cpan, you need to copy /etc/perl/CPAN/ to ~/.cpan/CPAN/ and edit it: where it contains /root/.cpan you need to put the full path to the .cpan directory in your home directory, eg /home/myuser/.cpan.

Using your private CPAN repository in Foswiki

CPAN libraries in Foswiki's foswiki/lib/CPAN (technically speaking, foswiki/lib/CPAN/lib ) directory are automatically detected and used by Foswiki; you don't have to do anything else!

If, however, you've installed shared CPAN libraries elsewhere, you have to point to it. Update @localPerlLibPath in bin/LocalLib.cfgin your Foswiki installation:

@localPerlLibPath = ( "/home/foswiki/lib/CPAN/lib" );

If you are trying to cause an upgraded version of a CPAN module to be used by Foswiki, but can't upgrade because of a situation such as a hosting provider, you must first create the private CPAN repository (preferably use foswiki/lib/CPAN/lib) and then you need to "trick" Foswiki into using it before the default locations. The localPerlLibPath value will be appended to Perl's @INC array; existing paths will take precedence, so it won't work. In order to put a path at the beginning of the @INC array, you need to put it in $CPANBASE. Add the following line to bin/LocalLib.cfg right after $foswikiLibPath:

$CPANBASE = "/full/path/to/foswiki/lib/CPAN/lib";

Installing CPAN modules manually

If you are behind a hefty firewall and cannot run CPAN and your Unix machine does not have ready made packages available the method is to manually install the package. Some packages contains binary compiled modules and requires a fully working Perl and C development environment (including a C compiler and make tool).

First we download them. The most common ones you need are here. (pick the latest version if there is a newer)

Then we install them. This is done more or less the same way with all of them. At least one module depends on FreezeThaw so install that first.

  • Untar the package in some temporary directory with tar -zxvf filename.tar.gz
  • Run these commands (look in the readme file - maybe there are extra steps
   perl Makefile.PL
   make test
   make install

  • You can delete the entire directory with the sources afterwards if you desire.
  • Windows users - download Nmake from microsoft website, and use 'nmake' instead of make in the above set of commands
Note: Above process is slightly different on Solaris 10 (onwards) compared to Linux. Instead of running perl Makefile.PL you must run /usr/perl5/bin/perlgcc Makefile.PL. Apart from this all is the same. See SolarisInstallCookbookPerlModules for full explanation.

ActiveState Perl

ActiveState has provided compiled modules that make CPAN installation very easy:
  1. Browse to the ActivePerl PPM archives
  2. Select your ActivePerl version (8xx means perl 5.8)
  3. Select your operating system. This procedure has been successfully used to extend the set of CPAN modules provided with the Windows Installer for TWiki 4.2.0. However ActiveState also provides downloads for Darwin, HP-UX, Linux, and Solaris.
  4. Download the module(s) you need. File are named xxx-xxx, not xxx::xxx.
The rest of these steps only apply to Windows downloads from ActiveState:
  1. Extract the ZIP(s) to a directory on the server, e.g., . Warnings about overwriting README files during extraction can be safely ignored. The installer expects the ZIP to be extracted directly in that directory, and not in sub-directories for each module. So the directory will contain *.ppd files and a directory called which contains *.gz files.
  2. Start the GUI for the Perl Package Manager that was installed with ActivePerl: i.e., Start > Run... > ppm
  3. In the program Preferences, check that Areas points to your Perl install. "Add Repository" for the directory with the extracted modules.
  4. The modules should now appear in the list. Right-click + Install to mark them to be installed. Click as many as needed, and it will check the pre-requisites as it goes.
  5. Under the File menu, select "Run Marked Actions". Check for errors, and that's it: no need to restart Apache or re-Configure plug-ins.
Unfortunately a PPM package isn't always available (and I couldn't get nmake to work). In those cases:
  1. Open the URL
  2. Download the PPD (IE downloads it as XML, just rename it)
  3. Also download the ZIP from the location specified in the PPD file
  4. Extract the ZIP and edit install-nomake to change the shebang from #!/bin/sh to #!D:/perl/bin/perl (or wherever you perl is)
  5. At a command prompt (the -s flag, described in the comments of install-nomake, installs it to a remote directory of your choosing):
    cd D:\download_location
    perl install-nomake -s D:\Perl\site

MiniCPAN details a mechanism to mirror the latest version of CPAN modules. this will grab all the CPAN modules and create a local mirror.

Contributors: MartinCleaver, CrawfordCurrie, WillNorris, PeterThoeny, KennethLavrsen, LarsBruunxHansen, SvenDowideit - 07 Jul 2007


Debian also has dh-make-perl ; if the repos don't have the cpan module, you can always make it yourself. needs fakeroot, a bit of sense, and disk space (also you'll need to configure CPAN via the way mentioned above).

-- SimonRaven - 20 Sep 2007

dh-make-perl looks useful - enables Ubuntu as well as Debian users to create .debs that are easily tracked through APT - see this dh-make-perl tutorial.

-- RichardDonkin - 20 Sep 2007

For windows, on 64 bit systems, use dmake:

-- NicolaeRacovita - 16 Dec 2011

I've recently discovered CPAN Minus (cpanm) which appears to be a lighter-weight option for installing needed CPAN modules in local directories. It takes less overhead than CPAN proper so is more compatible with shared hosting.

-- LynnwoodBrown - 15 Aug 2013

For Gentoo linux, I've installed the following ebuilds for basic Foswiki operation:
 dev-perl/Authen-SASL     (Needed for perl to authenticate to a SMTP email server)
 dev-perl/IO-Socket-SSL   (Needed for perl to support encrypted email connection:  STARTTLS or SSL)

Some of these pull in other dependencies, but these are listed in my world file.

-- GeorgeClark - 05 Jan 2014

BasicForm edit

TopicClassification SupplementalDoc
Topic Summary
Interested Parties
Related Topics
Topic revision: r19 - 01 Jul 2015, CrawfordCurrie - This page was cached on 01 Sep 2015 - 03:16. Get a fresh version here.
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License