I installed a module successfully with CPAN, but perl can't find it. Why?

Question

I installed a CPAN module like this:

cpan Acme

According to the output, the installation was successful:

Running install for module 'Acme'
...
All tests successful.
Files=2, Tests=3,  0 wallclock secs ( 0.02 usr  0.00 sys +  0.04 cusr  0.00 csys =  0.06 CPU)
Result: PASS
  INGY/Acme-1.11111111111.tar.gz
  /usr/bin/make test -- OK
Running make install
Manifying 1 pod document
Installing /home/foo/perl5/lib/perl5/Acme.pod
Installing /home/foo/perl5/lib/perl5/Acme.pm
Installing /home/foo/perl5/man/man3/Acme.3pm
Appending installation info to /home/foo/perl5/lib/perl5/x86_64-linux-thread-multi/perllocal.pod
  INGY/Acme-1.11111111111.tar.gz
  /usr/bin/make install  -- OK

But when I try to use the module, I get an error:

$ perl -MAcme -e1
Can't locate Acme.pm in @INC (@INC contains: /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5/vendor_perl /usr/share/perl5/vendor_perl /usr/lib64/perl5 /usr/share/perl5 .).
BEGIN failed--compilation aborted.

Why can't perl find the module even though it was installed successfully? How can I fix this?

Answer 1

The module was installed here:

/home/foo/perl5/lib/perl5/Acme.pm

But perl looks for modules in @INC, which in this case contains:

/usr/local/lib64/perl5
/usr/local/share/perl5
/usr/lib64/perl5/vendor_perl
/usr/share/perl5/vendor_perl
/usr/lib64/perl5
/usr/share/perl5
.

(. refers to the current working directory.)

Since the module is not in @INC, perl can't find it without some help.

Why did CPAN install the module outside of @INC?

A common cause is configuring CPAN to bootstrap local::lib so that modules are installed in your home directory instead of in the system Perl directories. If you have CPAN 1.9463 or higher and you don't have write permissions in the default install path, the first time you run CPAN you will be prompted:

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')
 [local::lib]

If you choose to bootstrap local::lib (the default), the module will be installed inside ~/perl5. You may also be prompted something like:

Would you like me to append that to /home/foo/.bashrc now? [yes]

If you choose yes (the default), some variables will be added to your .bashrc (or the equivalent for your shell) so that when you run CPAN in the future, modules will continue to be installed in your home directory:

PATH="/home/foo/perl5/bin${PATH+:}${PATH}"; export PATH;
PERL5LIB="/home/foo/perl5/lib/perl5${PERL5LIB+:}${PERL5LIB}"; export PERL5LIB;
PERL_LOCAL_LIB_ROOT="/home/foo/perl5${PERL_LOCAL_LIB_ROOT+:}${PERL_LOCAL_LIB_ROOT}"; export PERL_LOCAL_LIB_ROOT;
PERL_MB_OPT="--install_base \"/home/foo/perl5\""; export PERL_MB_OPT;
PERL_MM_OPT="INSTALL_BASE=/home/foo/perl5"; export PERL_MM_OPT;

How can I fix it?

If CPAN added the above environment variables to your .bashrc (or equivalent), the simplest thing to do is start a new shell (or source your .bashrc). This will set PERL5LIB so that perl can find modules installed in ~/perl5.

On the other hand, if you have sudo access and you want CPAN to install modules in the system Perl directories instead of in your home directory, delete the environment variable settings from your .bashrc (or equivalent), start the CPAN shell, and run:

o conf init

This will reset the CPAN configuration. You will be prompted again if you want to bootstrap local::lib; enter "sudo" instead. In general, I wouldn't recommend doing this; it's usually better to use your distro's package manager (e.g. yum, apt) to install modules in the system Perl directories.

Also see: How do I 'use' a Perl module in a directory not in @INC?