Using CPAN with a non-root account

Customize @INC via PERL5LIB | Switching the Install User | Other

Root access is not required to install Perl modules. Perl modules can be installed under a home directory, or into any other location. When possible, use the local::lib module.


Installs from CPAN may not be reproducible, as the author could upload a new, incompatible module version, or delete the entire module without warning (though old versions of the module may be available on backpan). If this is a concern, be sure to archive the specific module versions required for the software, so that the installation can be properly reproduced on other systems or again in the future.

Multiple perl Installed?

Another important piece of information is the number of perl installed on the system. Ensure that only one version of perl is used consistently for each software project—usually by using the fully qualified path, or by ensuring that all required environment settings are consistent and correct—as otherwise modules may end up installed for the wrong version of perl.

$ type -a perl
perl is /usr/bin/perl
perl is /usr/local/bin/perl
$ whence -a perl

Some vendors (notably Apple in recent Mac OS X releases) may install multiple versions of perl by default, and may offer a means to switch between these different versions. This might also complicate module installation and usage.

$ ls /usr/bin/perl5*
/usr/bin/perl5.10.0 /usr/bin/perl5.8.9

Clean Slate

Previous build or configuration attempts may have left the system in a messy state. If possible, use a virtual system, so that a build system can easily be rebuilt, or restored to a known clean slate. Another method is to create a new system account, and build software under that, destroying the home directory when done to reset to a clean slate. If this is not possible, reset CPAN to a clean slate by wiping out the ~/.cpan directory. The system-wide CPAN configuration should have no bearing on user-specific build attempts, though for reference can be located by running:

$ perl -le 'print grep -f, map "$_/$ARGV[0]", @INC' CPAN/

When using local::lib with CPAN, accept the defaults during the cpan configuration questions (that is, make no changes to the prompted configuration settings), then bootstrap local::lib.

Customize @INC via PERL5LIB

See customizing @INC via PERL5LIB (among other options to customize @INC for perl), or follow the documentation in local::lib.

Switching the Install User

Use the make_install_make_command option to build as one user, but install as a different one:

cpan> o conf make_install_make_command 'sudo /usr/bin/make'

And also the following for Module::Build, which is probably why I stick to Module::Install, as duplicate-but-different configuration requirements are one of the several things that annoy me about Module::Build:

cpan> o conf mbuild_install_build_command 'sudo ./Build'

However, since Module::Build lacks a separate "build" versus "install" as the alternatives do, the sudo ./Build may pollute the build directory with files owned by some other user. This may require other commands to periodically cleanup or otherwise rectify the permissions on these files so the original user can manage the build directory. I recommend any of Module::Install, Dist::Zilla, or ExtUtils::MakeMaker over Module::Build.


The UNINST=1 option should not be set for non-root configurations, as this will cause the user process to attempt to remove any conflicting modules, often those present in the system @INC paths. So do not set this option for a non-root configuration.