Can't locate ... in @INC

The “Can’t locate … in @INC” error means Perl cannot find the module loaded with use or require in any directory listed in the @INC array.

What It Means

When you write use Some::Module, Perl searches through the @INC array — a list of directory paths built into the interpreter and extended by environment variables and command-line flags. If the file Some/Module.pm does not exist in any of those paths, Perl stops with this error. @INC typically includes system library directories, the current directory, and paths set by PERL5LIB.

Why It Happens

• The required CPAN module is not installed on your system.
• The module is installed but in a non-standard location not included in @INC.
• The PERL5LIB environment variable is empty or points to the wrong directory.
• You are using a Perl version different from the one that installed the module.
• The module name has a typo or the filename does not match the package name.
• You are running a script from a directory that was removed from @INC in Perl 5.26+.

How to Fix It

1. Install the missing module via CPAN

# Install with the CPAN shell
cpan Some::Module

# Or with cpanm (recommended — faster and simpler)
cpanm Some::Module

2. Install via your system package manager

# Ubuntu / Debian
sudo apt install libsome-module-perl

# CentOS / RHEL / Fedora
sudo dnf install perl-Some-Module

3. Add a custom library path with use lib

If you have modules in a local directory:

use lib '/home/user/perl5/lib';
use Some::Module;    # Now found

4. Set the PERL5LIB environment variable

export PERL5LIB="/home/user/perl5/lib:$PERL5LIB"
perl script.pl

Add to your shell profile (~/.bashrc or ~/.zshrc) for permanence.

5. Verify the module name and filename match

# The file must be named Module.pm and define package Module;
ls /path/to/lib/Some/Module.pm

6. Check your Perl version compatibility

perl -v
# Some modules only work with specific Perl versions
cpanm Some::Module   # Installs the correct version for your Perl