How to Install CPAN Modules
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,
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
prefix, and replace
). 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. You may need to first install
EPEL is Extra Packages for Enterprise Linux
For Debian based distributions, including Ubuntu, the naming convention is a little different. For example, the CGI::Session library is called libcgi-session-perl. (Change to lowercase, add
suffix). 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
installs the CGI::Session module from CPAN. You can also use GUI tools such as Synaptic to find and install such modules.
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
, 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 http://packages.gentoo.org/packages/?category=dev-perl
for an overview of Perl CPAN related ebuilds.
Install CPAN modules into your local Perl library using
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. (Generally running as root is not
recommended.) 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,
is installed into the System perl libraries, and then
curl -L https://cpanmin.us | perl - App::cpanminus
Check your system documentation. You may be able to install
using system tools.
apt-get install cpanminus
- RedHat /Centos:
yum install perl-App-cpanminus (Requires EPEL also be installed
yum install epel-release)
Setting up a private CPAN library
If you 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. Previous versions of this topic documented the old way to do this using CPAN.
- Install CPAN:App::cpanminus documented above.
- If you can change your Foswiki installation directories:
- Change to your Foswiki lib directory, typically
- If you can NOT change your foswiki installation directly, create a CPAN directory in your local home directory.
cpanm -l CPAN Package::To::Install (-l is lowercase letter L )
This will create the CPAN directory and install the requested packages in that location.
~ $ cpanm -l CPAN Crypt::Eksblowfish::Bcrypt
--> Working on Crypt::Eksblowfish::Bcrypt
Fetching http://www.cpan.org/authors/id/Z/ZE/ZEFRAM/Crypt-Eksblowfish-0.009.tar.gz ... OK
Configuring Crypt-Eksblowfish-0.009 ... OK
==> Found dependencies: Class::Mix
--> Working on Class::Mix
3 distributions installed
~ $ ls CPAN
Using your private CPAN repository in Foswiki
CPAN modules installed directly into Foswiki's
) directory are automatically detected and used by Foswiki. The Foswiki:Extensions.CpanContrib
places modules directly into
cpanminus builds into a different library structure
must be edited.
in your Foswiki installation. The actual installation directories will vary based upon your system architecture. Two libraries are required; one for the platform independent modules, and one for architecture specific modules. For example, the above install created:
│ └── perl5
│ ├── Class
│ │ └── Mix.pm
│ └── x86_64-linux
│ ├── auto
CPAN/lib/perl5 contains the pure perl modules
CPAN/lib/perl5/x8_64-linux contains the architecture specific modules.
However you should also add the lib directory, so that any modules installed by the Foswiki:Extensions.CpanContrib
override any system modules. The specific
setting for this installation is:
@localPerlLibPath = (
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).
If you have a machine using the same architecture as your server that can access the Internet
, install cpanminus on that system, install the required modules into a local CPAN directory, and copy the installed CPAN library to the Foswiki server.
If you do not have access to a machine with the same architecture.
you can use tools like CPAN:CPAN::mini
to create your own local mirror of CPAN.
- Install CPAN:CPAN::Mini
- Mirror all of CPAN to a local directory:
minicpan -l mycpan (This is very large - 1 Gig or larger, and takes a long time to download!)
- move the complete mycpan structure over the the Foswiki server.
- Install modules on the Foswiki system using cpanm, with the -M option, specifying the path to the mirror:
cpanm -M /path/to/mycpan Module::To::Install
ActiveState has provided compiled modules that make CPAN installation very easy:
- Browse to the ActivePerl PPM archives
- Select your ActivePerl version (8xx means perl 5.8)
- 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.
- Download the module(s) you need. File are named
The rest of these steps only apply to Windows downloads from ActiveState
- 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
- Start the GUI for the Perl Package Manager that was installed with ActivePerl: i.e., Start > Run... > ppm
- In the program Preferences, check that Areas points to your Perl install. "Add Repository" for the directory with the extracted modules.
- 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.
- 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
to work). In those cases:
- Open the URL http://trouchelle.com/ppm/
- Download the PPD (IE downloads it as XML, just rename it)
- Also download the ZIP from the location specified in the PPD file
- Extract the ZIP and edit
install-nomake to change the shebang from
#!D:/perl/bin/perl (or wherever you perl is)
- At a command prompt (the
-s flag, described in the comments of
install-nomake, installs it to a remote directory of your choosing):
perl install-nomake -s D:\Perl\site
- badlink-->http://sial.org/howto/perl/life-with-cpan/ - good introduction to CPAN modules, and different ways to install them
- http://www.perl.com/pub/a/2002/04/10/mod_perl.html - good description of how to do local installs of Perl modules without superuser privileges
- 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).
- 20 Sep 2007
looks useful - enables Ubuntu as well as Debian users to create .debs that are easily tracked through APT - see http://www.debian-administration.org/articles/78
this dh-make-perl tutorial.
- 20 Sep 2007
For windows, on 64 bit systems, use dmake: http://tools.openoffice.org/dmake/dmake_4.6.zip
- 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.
- 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.
- 05 Jan 2014
The first of the external links no longer points where it should. I've made it non-clickable.
- 04 Jul 2016