• DreamHost does not directly support any of the features described on this page. Use at your own risk!
  • Support for these instructions is not available from DreamHost tech support.
  • Server changes performed by DreamHost may break your modifications. You, as the user, are responsible for troubleshooting and resolving issues with your customizations.
  • If you require root/sudo access to run a command, you must upgrade to a Dedicated server and add an admin user.

CPAN is the Comprehensive Perl Archive Network and allows you to use the HUGE library of premade modules available at

You need root access normally, but this article will show you how to setup CPAN as a non-root user.

Setting up CPAN

  1. To install modules in your home directory, set up a target directory for them:
    [server]$ $ mkdir ~/perlmods
  2. To ensure that Perl knows where the new modules are going to be installed, add the following lines to the bottom of your ~/.profile file:
    export PERL5LIB

    where 5.x and 5.x.x refer to the current version of Perl installed on the DreamHost servers. (You can find the version with `perl -v`.)

  3. Log out from DreamHost and then log in again.
  4. Set up CPAN to install the modules in the new path, and then run cpan. If this is the first time you run it it will go directly into configuration mode:
    [server]$ cpan

    You must use the cpan command, rather than perl -MCPAN. The latter command is not recognized as an installer, and is subject to more stringent memory limits.

  5. If the CPAN setup doesn't come up, enter "o conf init" at the cpan> prompt.
    Are you ready for manual configuration? yes
    Policy on building prerequisites (follow, ask or ignore)? follow
    Parameters for the 'perl Makefile.PL' command?
    Typical frequently used settings:
    PREFIX=~/perl non-root users (please see manual for more hints)
    Your choice: PREFIX=~/perlmods
    Select your continent (or several nearby continents) [] 5
    Select your country (or several nearby countries) [] 6
    put them on one line, separated by blanks, e.g. '1 4 5' [] 14 7 1 2 3 (whatever you like)
    • The important options are that you want to do a manual configuration, and the PREFIX= line.
    • The prerequisite line is optional but easier overall.
    When finished, the following cpan> command prompt appears:
    [server]$ cpan> install XRAY::Vision
  6. Type "install Some::Module", where Some::Module is the name of the module you are trying to install. See the example above, which installs it in the perlmods directory.
  7. When finished, enter the following to exit the CPAN shell:
    [server]$ cpan> bye
  8. To confirm if a Module is installed (or if you need to add it or not), enter the following at a shell login:
    [server]$ perl -MXRAY::Vision -e 1
    • If the module is installed in the root perl install, you won't get any errors; it will just return silently.
    • If the module is not already installed in the root perl install, you will get something like this:
    [server]$ perl -MXRAY::Vision -e 1
    Can't locate XRAY/ in @INC (@INC contains: /etc/perl /usr/local/lib/perl/5.8.4 .... etc

Making your FastCGI / CGI scripts work

Any CGI or Fast CGI scripts must have the following at the top in order to use the locally installed modules:

use lib qw( /home/username/perlmods/lib/perl/5.x /home/username/perlmods/lib/perl/5.x.x 
            /home/username/perlmods/share/perl/5.x /home/username/perlmods/share/perl/5.x.x
            /home/username/perlmods/local/lib/perl/5.x.x );

where username is your shell name, perlmods is what you chose above as the local CPAN install directory, and 5.x and 5.x.x refer to the currently installed Perl version determined by perl -v.

What if I see an error?

If the above cpan command generates an error like the following:

Your configuration suggests that should use a working
directory of
Unfortunately we could not create the lock file
due to permission problems.

Please make sure that the configuration variable
points to a directory where you can write a .lock file. You can set
this variable in either

Could not open >/root/.cpan/.lock: Permission denied

then you must manually create a ~/.cpan/CPAN/ file before proceeding to the next step (this is because root already configured cpan in your host.)

You can do this by entering the following:

mkdir -pv ${HOME}/.cpan/CPAN
cat > ${HOME}/.cpan/CPAN/ <<eof

\$CPAN::Config = {
  'auto_commit' => q[0],
  'build_cache' => q[10],
  'build_dir' => q[\$ENV{HOME}/.cpan/build],
  'cache_metadata' => q[1],
  'commandnumber_in_prompt' => q[1],
  'cpan_home' => q[\$ENV{HOME}/.cpan],
  'dontload_hash' => {  },
  'ftp' => q[/usr/bin/ftp],
  'ftp_passive' => q[1],
  'ftp_proxy' => q[],
  'getcwd' => q[cwd],
  'gpg' => q[/usr/bin/gpg],
  'gzip' => q[/bin/gzip],
  'histfile' => q[\$ENV{HOME}/.cpan/histfile],
  'histsize' => q[100],
  'http_proxy' => q[],
  'inactivity_timeout' => q[0],
  'index_expire' => q[1],
  'inhibit_startup_message' => q[0],
  'keep_source_where' => q[\$ENV{HOME}/.cpan/sources],
  'lynx' => q[/usr/bin/lynx],
  'make' => q[/usr/bin/make],
  'make_arg' => q[],
  'make_install_arg' => q[],
  'make_install_make_command' => q[/usr/bin/make],
  'makepl_arg' => q[PREFIX=\$ENV{HOME}/perlmods],
  'mbuild_arg' => q[],
  'mbuild_install_arg' => q[],
  'mbuild_install_build_command' => q[./Build],
  'mbuildpl_arg' => q[],
  'ncftpget' => q[/usr/bin/ncftpget],
  'no_proxy' => q[],
  'pager' => q[less],
  'prerequisites_policy' => q[follow],
  'scan_cache' => q[atstart],
  'shell' => q[/bin/bash],
  'tar' => q[/bin/tar],
  'term_is_latin' => q[0],
  'term_ornaments' => q[1],
  'unzip' => q[/usr/bin/unzip],
  'urllist' => [q[], q[], q[], q[]],
  'use_sqlite' => q[0],
  'wget' => q[/usr/bin/wget],

Installing Module::Build and many other modules

If you're installing Module::Build or others which use Module::Build in their installation, it might help to add the above PERL5LIB lines to your .profile (or .bash_profile), otherwise anything you build won't know how to read the Module::Build Build script.

Other modules

Please note that some modules will not install correctly from CPAN as non-root and to a non-standard path. They must be built and installed manually (that is, using the build scripts provided with the modules). Two specifically are:


DateTime (as of 0.68) requires the install step to be executed like so using the "--install_base" option:

[server]$ ./Build install --install_base ~/perlmods


IO::Compress (as of 2.034) requires tweaking the Makefile because one of the target paths ignores the PREFIX environment variable.

  1. Generate the Makefile using:
    [server]$ perl Makefile.PL PREFIX=~/perlmods
  2. Open up the Makefile and look for this line:
    INSTALLARCHLIB = /usr/lib/perl/5.10
  3. Change it to say:
    INSTALLARCHLIB = $(SITEPREFIX)/lib/perl/5.10
  4. Proceed with your make/make test/make install.

Configuring CPAN

If you need to manually configure settings, you can access your configuration in the file:


If specifying PREFIX as above, then use the full path to your perlmods directory:


Use perldoc to get a listing of CPAN settings that you can edit:

[server]$ perldoc CPAN

Using CPAN Minus and local::lib

Tatsuhiko Miyagawa's CPAN Minus (github cpan) makes it even easier to add support for your own Perl modules. Use

[server]$ cpanm -L ~/perlmod module ...

to install modules into ~/perlmod. In your script, enter the following:

use local::lib '~/perlmod';

to use these modules.


There is a procwatch daemon running that may kill your perl installs. Visit the procwatch article for more information.


Did this article answer your questions?

Article last updated .