How to Fix Perl Can’t Locate CGI.pm Error on Windows?
When you run a Perl script on Windows and see the message “Can’t locate CGI.pm in @INC”, the program stops right away. This error means the script can’t load the CGI module, which many older web apps and tools depend on. Without it, your project won’t run, and you can’t test or deploy code. In this guide, you’ll learn what the error means, where it shows up, the common causes, and how to prevent it from returning in the future.
What is “Can’t Locate CGI.pm in @INC”?
The error happens when Perl tries to use the CGI.pm library but doesn’t find it in its search path. That search path is called @INC, a list of folders where Perl looks for modules. If CGI.pm isn’t in any of those folders, the interpreter fails.
Most users see the error in the terminal when running commands like perl script.pl. Others find it in server logs when using IIS or Apache with Perl CGI scripts. Instead of running normally, the script crashes and prints “Can’t locate CGI.pm in @INC … BEGIN failed … compilation aborted.”
Common Causes of the Error
This message can come from several issues. Here are the most frequent ones on Windows:
- CGI.pm not installed in your Perl distribution (Strawberry Perl, ActivePerl, etc.)
- Multiple Perl versions on the system, with PATH pointing to the wrong one
- @INC not including the folder where CGI.pm is installed
- Proxy or SSL restrictions blocking downloads from CPAN
- ActivePerl’s old PPM repositories no longer hosting CGI.pm
- Antivirus or Windows permissions stopping module installation
- Oddities in script execution, like CRLF line endings or incorrect shebang lines
How to Fix “Can’t Locate CGI.pm” Error on Windows
The error shows because Perl can’t load CGI.pm from its search paths. Different issues cause this, so each fix addresses one of them.
Fix #1: Install CGI.pm from CPAN
This error often happens because CGI.pm isn’t installed in your Perl environment.
Here are the steps you can follow:
- Open Command Prompt or PowerShell.
- Run:
cpan CGI - If you have
cpanminstalled, run:cpanm CGI - Wait for the installation to finish.
- Run:
perl -MCGI -e "print $CGI::VERSION"to confirm.
After this, CGI.pm is placed in your Perl library path, and the error no longer appears.
Fix #2: Check Which Perl You’re Using
On Windows, it’s common to have multiple Perl installs (Strawberry Perl, ActivePerl, WSL Perl). If the wrong one is in PATH, scripts run with a version that doesn’t have CGI.pm.
Run where perl in Command Prompt. If you see more than one path, confirm which one should be used. Remove extra entries from PATH if needed. Once the right perl.exe is active, Perl can find the modules you installed.
Fix #3: Set PERL5LIB or Update @INC
Sometimes the module is installed but not in @INC. This means Perl doesn’t know where to look.
Here are the steps you can follow:
- Find the folder where CGI.pm is located (usually under
site/lib). - In PowerShell, run:
setx PERL5LIB "C:\path\to\perl\site\lib"
- Restart the terminal.
After setting this, @INC includes the right folder, and Perl loads CGI.pm without failing.
Fix #4: Use local::lib for User Installs
If you don’t have admin rights or antivirus blocks system installs, you can install CGI.pm locally.
Run:
cpanm --local-lib=~/perl5 CGIsetx PERL5LIB "%USERPROFILE%\perl5\lib\perl5"
This installs CGI.pm in your user directory. After that, Perl finds the module under PERL5LIB, and the error clears.
Fix #5: Handle Proxy or SSL Restrictions
If you’re behind a corporate firewall, CPAN can’t download CGI.pm. Perl then fails with the module not found error.
Set your proxy before running CPAN:
set HTTP_proxy=http://proxy.company.com:8080set HTTPS_proxy=http://proxy.company.com:8080
With the proxy set, CPAN installs CGI.pm successfully, and scripts run again.
Fix #6: Check Permissions and Antivirus
Sometimes the module installs but can’t be written to the library folder because of antivirus or permissions. Run your terminal as Administrator and retry installation. If antivirus blocks Perl, add an exception. Once permissions are fixed, Perl can load CGI.pm from its library paths.
Fix #7: Upgrade from Old ActivePerl
ActivePerl’s PPM repositories no longer host CGI.pm. If you’re still on ActivePerl, you’ll keep hitting this error.
The solution is to switch to Strawberry Perl, which comes with CPAN support. After migration, you can install CGI.pm like any other module, and the error won’t return.
Prevention Tips to Avoid Can’t Locate CGI.pm
You can avoid running into this error again by setting up a stable Perl environment and keeping it consistent. Simple habits help a lot:
- Stick to one main distribution like Strawberry Perl and make sure it’s in PATH
- Use local::lib or project-specific library paths for installs
- Keep documentation of proxy or certificate settings if you’re behind a firewall
- Save dependencies in a cpanfile for easy reinstallation
- Don’t mix WSL Perl and native Windows Perl in the same project
- Run a quick test with
perl -MCGI -e "print $CGI::VERSION"before deploying - Consider moving new projects to Plack or Mojolicious instead of CGI.pm for long-term support
Conclusion
The “Can’t locate CGI.pm in @INC” error tells you Perl can’t find the CGI module in its search paths. It’s a common roadblock when running legacy scripts or setting up Perl on Windows for the first time.
By understanding the causes — from missing modules to PATH misconfigurations — and applying prevention tips like using one distribution and keeping dependencies clear, you reduce the risk of hitting the same problem again. If the error still shows up after trying fixes, checking logs or reaching out to Perl community forums can help you get back on track.
