cpan2Add my vote for this tag installation4Add my vote for this tag create new tag
, view all tags
Get Involved!
TWiki is an open source project with 10+ years of history, built by a team of volunteers from around the world, and used by millions of people in over 100 countries. The community is focusing on building the best collaboration platform for the workplace. We invite you to get involved!

ALERT! NOTE: This is a SupplementalDocument topic which is not included with the official TWiki distribution. Please help maintain high quality documentation by fixing any errors or incomplete content. Put questions and suggestions concerning the documentation of this topic in the comments section below! Use the Support web for problems you are having using TWiki.

How to Install CPAN Modules


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

The TWiki package contains most required non-standard CPAN modules. Usually you have to install a few extra CPAN modules to use all the features in TWiki. If you install additional plugins you might need to install additional CPAN modules. 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.

What Do I Need?

These are the CPAN modules that you are recommended to install

  • CGI::Session - Needed for TWiki's session feature which is really a must have
  • Error - Needed if you later want to develop plugins. It is also distributed with TWiki but the author has experienced lots of trouble with the build script that builds plugins which sometimes cannot find this library. By adding it to the site Perl library you avoid this kind of trouble.
  • FreezeThaw - an indirectly needed module used by other modules.
  • GD - Used by the pluging that can produce graphics such as TWiki:Plugins.ChartPlugin. It requires that lib gd is installed. If your choice of installation does not include you simply need to install the rpms gd and gd-devel. They are both on the CDs or DVD.
  • HTML::Tree - Needed by some popular plugins
  • Time-modules (Time::CTime, Time::DaysInMonth, Time::JulianDay, Time::ParseDate, Time::Timezone) also needed by some popular plugins.
This list may not be complete. For example if RHEL/Fedora/CentOS Linux was not installed as "Software Development" and "WebServer" you may need to install additional modules.

When you run configure in the section "CGI Setup" there is a subsection "Perl modules" which lists the version of the installed modules and also the missing modules.

What CPAN Libraries Do I Have?

To test if you have a certain 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"'

Install CPAN Modules using the package management system

If your system is one of the most 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 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 carries nearly all the CPAN libraries. E.g. Dag Wieers has all the RPMs you will ever need for CPAN libs for the RedHat/Fedora/Centos family.

For Debian based distros, 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 TWikiOnDebian and TWikiOnUbuntu for more.

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.

TWikiOnRedHat 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 CPAN

By default, you need to have admin (root) privileges to install Perl modules - see the next section if you don't.

Installation is straightforward if your machine has Internet access. It is assumed that you have the CPAN perl module installed (this is normally the case).

The make utility must be available before using Bundle::CPAN. On CentOS 6.3 minimal you must run yum install make.

Invoke the CPAN shell:

# perl -MCPAN -e shell

If you run this for the first time it asks you some configuration questions. In most cases it works just fine if you tell it to "go figure it out yourself." Once configured you will see a cpan> shell prompt.

The first thing you should do is to upgrade your CPAN:

cpan> install Bundle::CPAN

Once ready, type:

cpan> reload cpan

Now it is time to install the additional modules you need. For example, to retrieve, configure and install the DateTime::TimeZone module, type:

cpan> install DateTime::TimeZone

If needed you will be prompted to install other modules this module depends on.

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 "yes" to automatic configuration, and wait for the noise to die down, or you can answer "no" 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/twiki/lib/CPAN/lib

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

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

Using your private CPAN repository in TWiki

CPAN libraries in twiki's twiki/lib/CPAN (technically speaking, twiki/lib/CPAN/lib ) directory are automatically detected and used by TWiki; 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/LocalSite.cfg in your TWiki installation:

@localPerlLibPath = ( "/home/twiki/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 http://trouchelle.com/ppm/
  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


http://www.perladvent.org/2004/5th/ details a mechanism to mirror the latest version of CPAN modules. this will grab all the CPAN modules and create a local mirror.

External Links

  • http://sial.org/howto/perl/life-with-cpan/ - good introduction to CPAN modules, and different ways to install them (dead link)
  • 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
Contributors: MartinCleaver, CrawfordCurrie, WillNorris, PeterThoeny, KennethLavrsen, LarsBruunxHansen, SvenDowideit - 07 Jul 2007

Comments & Questions about this Supplemental Document Topic

I moved above how-to from CpanReadme and enhanced it with a how-to on local Perl install.

-- PeterThoeny - 13 Oct 2006

The "type the following at the cpan prompt" textbox isn't displaying correctly. I'd fix it, but I don't know how. The textbox is interpreting the INSTALLMAN1DIR 's as WikiWords and is putting the little href ?s after them.

-- DustinGooding - 02 Mar 2007

Argh, the spec change of treating AAA1BBB as a WikiWord is biting us again. I fixed above text with noautolink tags.

-- PeterThoeny - 04 Mar 2007

This document needs two more sections.

How to install them under ActiveState in Windows [done, 2008-03-04] and how to install them under IndigoPerl.

-- KennethLavrsen - 27 Apr 2007

Nice additions, thanks Kenneth!

-- PeterThoeny - 27 Apr 2007

Have added Solaris specific notes in the "Installing CPAN modules manually" section.

-- LarsBruunxHansen - 02 Jul 2007

How to install CPAN modules on TWikiForWindowsPersonal?

-- CarloSchulz - 24 Jul 2007

Nice tips here - the instructions for private directory installation of CPAN modules can be slightly simplified. You just need to say o conf commit without a filename - cpan will use this filename by default, so I've simplified this above.

-- RichardDonkin - 11 Aug 2007

All you windows guys, just download the CPAN module. And the download Nmake15.exe from Microsoft and use it instead of the make command.

-- AnoopR - 30 Aug 2007

CGI::Session module is broken on CPAN.
See: http://www.nntp.perl.org/group/perl.cpan.testers/2007/09/msg602556.html
I am getting the same error. I am unable to force the install as I am using a hosted web service and do not have root access.

Any suggestions on how to fix CGI::Session ?
t/g4_dbfile_json................ok 51/101 (in cleanup) Dumping circular structures is not supported with JSON::Syck at /home/opeongon/.cpan/build/CGI-Session-4.20-Nox69o/blib/lib/CGI/Session/Serialize/json.pm line 18.
Seems to be known as well at CGI::Session /> I just need to know how to work around this problem.

-- KrisThompson - 09 Sep 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

Simon - dh-make-perl 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.

Kris - you don't need root to install your own CPAN libraries, see the section above on how to create a private CPAN setup.

-- RichardDonkin - 20 Sep 2007

I have a big problem with CPAN. [...refactored...] Can anybody help? Many thanks beforehand!

-- ThomasHesse - 25 Jan 2008

Olaf and Thomas: This section is to give feedback on the documentation of this topic. Please ask support questions in the Support web.

-- PeterThoeny - 03 Mar 2008

Thank you, will do.

-- OlafElder - 03 Mar 2008

Added a section for installation under ActiveState in Windows, as per suggestion by KennethLavrsen - 27 Apr 2007

-- SeanCMorgan - 04 Mar 2008

Hm, citation: "CPAN libraries in twiki's twiki/lib/CPAN (technically speaking, twiki/lib/CPAN/lib ) directory are automatically detected and used by TWiki; you don't have to do anything else!" Installed a fresh 4.2.0 on Windows (apache 2.2.8 and ActiveState Perl), and configure did not find twiki/lib/CPAN/lib/Error.pm. Worked around it by using shebang #!C:\perl\bin\perl -wT -I C:\Programme\TWiki\twiki\lib\CPAN\lib in configure. Have not found my error yet...

-- MarkHalpaap - 21 Mar 2008

I've installed and configured TWiki in my W2003 + Apache 2.2 + ActivePerl 5.8 and when browsing http://localhost:8080/twiki/bin/configure.pl I get "Failed to load the perl module TWiki::Configure::Checker. The module could not be found." .. "Can't locate TWiki/Configure/Checker.pm in @INC (@INC contains: C:/xampp/perl/site/lib/ C:/xampp/perl/site/lib C:/xampp/perl/lib . C:/xampp/apache)". The module exists but the script can't find it. Anybody knows why or how can I make it find it?

-- OscarPerez - 08 Apr 2008

Please ask support question in the Support web. This section is about the documentation of this topic.

-- PeterThoeny - 09 Apr 2008

All the modules mentioned in the "What Do I Need?" section are already packaged by Debian. So if you're running on that and have root access just run "aptitude install libcgi-session-perl liberror-perl libfreezethaw-perl libgd-gd2-perl libhtml-tree-perl libtime-modules-perl" and you're done. That will probably work on Ubuntu too.

-- MarkSheppard - 2010-10-21

Thanks Mark. Please feel free to enhance above doc.

-- PeterThoeny - 2010-10-21

I have followed this documentation, tried to install manually as wel as using redhat 6 packages and I still get that message when installing plugins :

 Warning: CPAN is not available, some installer functions have been disabled 

-- OlivierGuillard - 2012-02-08

This is a cross-post of Support.SID-01397.

-- PeterThoeny - 2012-02-08

The CPAN default these days appears to be

Would you like to configure as much as possible automatically? [yes] 
I changed the text above to match that.

-- Vicki Brown - 2014-03-07

Please use the Support forum if you have questions about TWiki features. This comment section is about the documentation of this topic.
Edit | Attach | Watch | Print version | History: r36 < r35 < r34 < r33 < r32 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r36 - 2014-03-07 - VickiBrown
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.