How to install Perl Modules from CPAN in the Unix user-space

If you're a sysadmin or if you run a Perl software development environment, you might want to give your users or developers the possibility to install Perl modules from CPAN into their private user-space. This could be helpful for trying out new modules or playing around with modules that might be used in production at a later time. Or, if a developer wants to test a new version of a module without overwriting the system-wide installed version of that module.

Here is a step by step instruction how you could set-up user-space CPAN support.

In the home-directory of the user, you need to create a file called


which is a customized configuration file for the CPAN shell. If you like, you could use the system-wide CPAN config as a template for this file and just overwrite the appropriate attributes.

One way to find the system wide CPAN config is by running a

locate CPAN/

and then copy the file over to ~/.cpan/CPAN/ Open the file in the editor of your choice and change the following lines:

'build_dir' => qq[$ENV{HOME}/.cpan/build],
'cpan_home' => qq[$ENV{HOME}/.cpan],
'histfile' => qq[$ENV{HOME}/.cpan/histfile],
'keep_source_where' => qq[$ENV{HOME}/.cpan/sources],
'makepl_arg' => q[PREFIX=~/lib/perl5 LIB=~/lib/perl5/lib INSTALLMAN1DIR=~/lib/perl5/man1 INSTALLMAN3DIR=~/lib/perl5/man3]
'mbuild_arg' => qq[--extra_linker_flags -L$ENV{HOME}/lib],
'mbuildpl_arg' => qq[--install_base $ENV{HOME}],

If you like to use a special CPAN mirror (maybe your own local mirror server) for the user, then also change the following line in

'urllist' => [q[], q[]],

Next you need to create the directories where the user-space Perl modules and man-pages will be installed to:


At last, you need to put the following lines into the users ~/.bash_profile (or whatever file your shell runs at login) file:

export PERL5LIB=${PERL5LIB}:~/lib/perl5/lib
export MANPATH=~/lib/perl5/man

which tells the Perl interpreter to look for modules first in ~/lib/perl5/lib and then search in the system wide directories. The same goes for the man-pages, which are living in ~/lib/perl5/man.

To give your new set-up a try, login with the user-account and install the following module:

cpan Acme::Bleach

and see if you can use it

man Acme::Bleach
perl -e 'use Acme::Bleach;'

One more thing :)

If you copy your brand-new set-up to /etc/skel


it will be installed automatically for each new Unix user that you create.

1 Comment

In your line:

'makepl_arg' => q[PREFIX=~/lib/perl5 LIB=~/lib/perl5/lib INSTALLMAN1DIR=~/lib/perl5/man1 INSTALLMAN3DIR=~/lib/perl5/man3]

are /perl5/man1 and /perl5/man3 correct?

According to your instructions later, we create a man directory in the library, but not a man1 or man3.


Leave a comment

About Marc

user-pic I am a Perl developer and CPAN author. I develop software with Perl since 1996 and Perl is still one of my favorite programing languages.