For cPanel & WHM version 11.52
Perl modules allow you to extend cPanel & WHM's functionality. For example, you can use Perl modules to add functions to cPanel & WHM.
Before you install a module, make certain that it will function correctly with the cPanel-provided Perl environments. For more information, read our Guide to Perl in cPanel & WHM documentation.
In the examples throughout this document,
Module::Name is the name of the custom Perl module that you wish to install.
Custom modules that ship with cPanel & WHM
Our upgrades to Perl may break custom code and modules that you used in previous versions of cPanel & WHM.
cPanel & WHM versions 11.46 through 54 ship with binaries that we compile against Perl version 5.14.4. This change directly affects any custom Perl code that you execute from cPanel binaries. It is critical that you test your plugins and hook code against Perl 5.14.4 to ensure it continues to work correctly. Previously compiled custom modules, with the
buildperl system, will not function properly in cPanel & WHM version 11.46 and later, because the system built the module against an older version of Perl.
Before you recompile all of your modules, check whether cPanel & WHM already includes your modules. With the addition of several modules to the list of modules that cPanel ships, we expect that cPanel & WHM ships with the majority of the modules that developers built with this tool.
- For a list of modules that cPanel currently ships, read our Third-Party Software documentation for the appropriate cPanel & WHM version.
cPanel wants to ensure that we ship the modules that developers need. If you discover that cPanel & WHM does not ship with a CPAN module that you need, send an email to firstname.lastname@example.org to request it.
While it is possible to install custom modules to the
/opt/cpanel/perl5/514/site_liblibrary with the
/usr/local/cpanel/3rdparty/perl/514/bin/cpancommand, this will cause further problems when cPanel switches to newer versions of Perl in the future.
Install modules to the system Perl binary
To install a Perl module to the system's Perl environment (
/usr/bin/perl), use one of the following methods:
|Install from the WHM interface.|
To install a module to the system Perl environment from the WHM interface, use the Module Installers interface (Home >> Software >> Module Installers).
To use this interface, you must have compiler access.
|Install from the command line with the |
When you use this script, you can include the
|Install from the command line with the ||The |
Install modules to the cPanel Perl installation
To install a Perl module to the cPanel-included Perl installation (
), use the following method:
When you use this tool, you must include, as an argument, the name of the module that you wish to install.
Confirm that your module installed correctly
To confirm that the modules you installed to the system's Perl binary are functional, run the following command, where
Module::Name is the name of the module:
To confirm that the modules you installed to the cPanel-included Perl installation are functional, run the following command, where
Module::Name is the name of the module:
If the command responds with the version of the module that you installed, the installation was successful.
Manage installed modules
/scripts/perlmods script allows you to use the
Perl::Mod module in order to manage the modules on your system.
Use the following flags to troubleshoot module installations:
-l— Use the
Perl::Modmodule to list all of the installed modules for your system.
-s— Use the
Perl::Modmodule to search for an installed module.
-u— Use the
Perl::Modmodule to uninstall modules.
Troubleshoot module problems
Error logs provide additional insight into problems on your server. cPanel & WHM writes
STDERR (standard error) output to the
/usr/local/cpanel/logs/error_log file whenever it encounters an error.
Some errors require that you use the
strace (system trace) command to view additional output that does not write to the
To view additional error information, run the following command while the system experiences the problem:
When you encounter
@INC array errors, you will see a message that resembles the following example in the
In this example, the system could not locate the Perl module. The error message also lists the locations in which the system searched for the module.
If you encounter this error, perform the following actions to resolve the problem:
- Place a copy of the module in one of the locations that the error message lists.
- Create a symlink from one of the listed location to the location of the module.
- Resolve an issue in the module itself during build time.
To view the current
@INC array paths, run the
perl -V command as the
root user. The system will return output that resembles the following example: