• 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.

The Comprehensive Perl Archive Network (CPAN) allows you to use an extensive library of pre-made modules available at

CPAN normally requires root access, but this article shows you how to set up CPAN as a non-root user.

In the following examples, username would be your Shell user and your website.

Setting up CPAN

  1. Log in to your server via SSH.
  2. Create the following directories:
    [server] mkdir ~/perl5/man
    [server] mkdir ~/perl5/man/man1
    [server] mkdir ~/perl5/man/man3
  3. Set up CPAN to install the modules. If this is the first time you run it, it goes 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.

  4. If the CPAN setup doesn't appear, enter o conf init at the cpan> prompt: requires configuration, but most of it can be done automatically.
    If you answer 'no' below, then enter an interactive dialog for each
    configuration option instead.
    Would you like to configure as much as possible automatically? [yes] yes
  5. Type yes and then press the Enter key:
    Warning: You do not have write permission for Perl library directories.
    To install modules, you need to configure a local Perl library directory or
    escalate your privileges.  CPAN can help you by bootstrapping the local::lib
    module or by configuring itself to use 'sudo' (if available).  You may also
    resolve this problem manually if you need to customize your setup.
    What approach do you want?  (Choose 'local::lib', 'sudo' or 'manual')
  6. Press the Enter key to accept local::lib:
    Now you need to choose your CPAN mirror sites.  You can let me
    pick mirrors for you, you can select them from a list or you
    can enter them by hand.
    Would you like me to automatically choose some CPAN mirror
    sites for you? (This means connecting to the Internet) [yes] yes
  7. Type yes and then click the Enter key. Let the script run until you see the following:
    local::lib is installed. You must now add the following environment variables
    to your shell configuration files (or registry, if you are on Windows) and
    then restart your command line shell and CPAN before installing modules:
    PATH="/home/username/perl5/bin${PATH:+:${PATH}}"; export PATH;
    PERL5LIB="/home/username/perl5/lib/perl5${PERL5LIB:+:${PERL5LIB}}"; export PERL5LIB;
    PERL_MB_OPT="--install_base \"/home/username/perl5\""; export PERL_MB_OPT;
    PERL_MM_OPT="INSTALL_BASE=/home/username/perl5"; export PERL_MM_OPT;
    Would you like me to append that to /home/username/.bashrc now? [yes] yes
  8. Type yes and then click the Enter key:
    commit: wrote '/home/username/.cpan/CPAN/'
    You can re-run configuration any time with 'o conf init' in the CPAN shell
    Your prompt changes to the following:
  9. Run the following. Make sure to change the username to your actual Shell username:
    cpan[1] o conf makepl_arg "install_base=/home/username/perl5 \
        LIB=/home/username/perl5/lib \
        INSTALLMAN1DIR=/home/username/perl5/man/man1 \
  10. Commit the changes:
    cpan[1] o conf commit
  11. Type exit to quit CPAN:
    cpan[1] exit
    This puts you back in your normal shell.

Installing modules

Now that everything is set up, you can install the modules.

  1. Open CPAN again:
    [server] cpan
  2. Type install Some::Module, where Some::Module is the name of the module you are trying to install:
    [cpan[1] install XML:Simple

Viewing modules

You can also check if and where modules are installed within CPAN. Type in the letter i followed by the module name. For example:

[cpan[1] i XML::Simple
Module id = XML::Simple
    CPAN_USERID  GRANTM (Grant McLean <>)
    CPAN_FILE    G/GR/GRANTM/XML-Simple-2.25.tar.gz
    UPLOAD_DATE  2024-04-08
    MANPAGE      XML::Simple - An API for simple XML files
    INST_FILE    /usr/share/perl5/XML/

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 .bash_profile, otherwise, anything you build won't know how to read the Module::Build Build script.

Other modules

Please note that some modules do 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:
    INSTALLARCHLIB = $(SITEPREFIX)/lib/perl/5.10
  4. Run make, make test, and 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 ) 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 monitor service running that may kill your perl installs. Visit the following article for more information.

See also

Did this article answer your questions?

Article last updated PST.

Still not finding what you're looking for?