Using CPAN with a non-root account

Configuration | Customize @INC

CPAN can be configured differently for each user, and can install modules to custom areas on a system. The sample configuration below installs modules under ~/lib/perl5, man pages under ~/share/man and (hopefully) everything else under the home directory. This approach also works for individual software trees required for special applications that run as non-privileged accounts: simply adjust the installation paths to suit the software depot in question.

Consult Life with CPAN for more information about the Comprehensive Perl Archive Network (CPAN). Consider also local::lib to bootsrap custom Perl module installation directories.


  1. Download the sample, and move it to ~/.cpan/CPAN/

    $ mkdir -p ~/.cpan/CPAN
    $ mv ~/.cpan/CPAN

  2. Customize the file.

    1. Change all occurences of HOMEDIRFIX to your home directory, for example /home/username.
    2. Review the makepl_arg arguments. For more information on the arguments, see ExtUtils::MakeMaker.
    3. Check the paths to various commands (e.g. wget), proxy settings for your environment, the urllist, and the shell.

      Be sure to remove the UNINST=1 option on make_install_arg for any non-system-wide configuration as otherwise CPAN will attempt to remove “shadowing” versions of the module installed for the site perl, leading to error messages involving forceunlink.

    4. Test for problems.

      $ perl -c syntax OK

  3. See below for the required PERL5LIB settings to customize @INC, if installing modules that depend on previously installed modules. Be sure to load the changes into your shell environment before running cpan, or to close and reopen your shell.
  4. Test the new configuration.

    To ensure Makefile are being generated with the proper paths, make a module from the CPAN shell, then review at the paths set in the resulting Makefile.

    cpan> make Text::Autoformat

    cpan> look Text::Autoformat

    $ less Makefile
    $ grep /home/username Makefile
    SITELIBEXP = /home/username/lib/perl5
    PREFIX = /home/username/
    INSTALLPRIVLIB = /home/username/lib/perl5
    INSTALLSITELIB = /home/username/lib/perl5
    INSTALLVENDORLIB = /home/username/lib/perl5
    INSTALLARCHLIB = /home/username/lib/perl5/darwin-thread-multi-2level
    INSTALLSITEARCH = /home/username/lib/perl5/darwin-thread-multi-2level
    INSTALLVENDORARCH = /home/username/lib/perl5/darwin-thread-multi-2level
    INSTALLMAN1DIR = /home/username/share/man/man1
    INSTALLSITEMAN1DIR = /home/username/share/man/man1
    INSTALLMAN3DIR = /home/username/share/man/man3
    INSTALLSITEMAN3DIR = /home/username/share/man/man3
    $ exit

    If the Makefile has the wrong path set for any variables, update the makepl_arg arguments in to set these variables to install to the proper custom location.

Customize @INC

Perl must be made aware of the custom /home/username/lib/perl5 library directory. Perl uses the @INC variable to hold library directories, though this varible must not be edited directly. For more information on @INC, consult perlvar (overview of variable), perlrun (command line arguments and environment variables), or lib (use lib pragma). Under a Bourne shell (such as zsh), use the following to set PERL5LIB and MANPATH environment variables.

if [ -d $HOME/lib/perl5 ]; then

Code running under Taint mode may require the use lib statement: see perlsec for details. Other applications may include different methods of setting custom environment setting, such as SetEnv under Apache:

SetEnv PERL5LIB /home/username/lib/perl5:/sw/lib/perl5