> ## Documentation Index
> Fetch the complete documentation index at: https://help.noxity.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Perl Modules

> Install and manage Perl modules from CPAN through cPanel's module manager.

Perl Modules installs CPAN modules into your account's local Perl tree, no SSH required. Useful when running Perl CGI scripts, mailing list software, or one-off cron jobs.

<Frame caption="cPanel home → Software → Perl Modules">
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/noxity/images/cpanel/software/perl-modules/page-light.png" alt="Perl Modules with installed list and search" className="block dark:hidden" />

  <img src="https://mintlify.s3.us-west-1.amazonaws.com/noxity/images/cpanel/software/perl-modules/page-dark.png" alt="Perl Modules with installed list and search" className="hidden dark:block" />
</Frame>

## Install a module

<Steps>
  <Step title="Search the catalog">
    Type the module name (e.g., `DBI`, `LWP::Simple`, `Email::MIME`). cPanel queries CPAN and shows matches.
  </Step>

  <Step title="Click Install next to the module">
    The module and its dependencies are compiled and dropped into `~/perl/`.

    Compilation can take a few seconds for small modules and a couple of minutes for things like `DBD::mysql` that pull in C dependencies.
  </Step>

  <Step title="Use it from your Perl script">
    The cPanel Perl wrapper adds `~/perl/lib/perl5/` to `@INC` automatically when you run scripts via the cPanel-managed shebang. If you're running scripts another way, add it yourself:

    ```perl theme={}
    use lib "$ENV{HOME}/perl/lib/perl5";
    use DBI;
    ```
  </Step>
</Steps>

## Update or uninstall

Both options sit next to **Install** in the installed-modules list. Same caveats as install: updates rebuild the module against the active Perl version; uninstall removes the files and any dependents that are now orphaned.

## When to use this vs `cpanm`

This tool wraps `cpanm` (cpanminus) under the hood. Anything you can install here you can also install over SSH:

```bash theme={}
cpanm --local-lib=~/perl Email::MIME
```

Use the cPanel UI when:

* You don't have SSH on your plan.
* You want a one-off install and the click is faster than typing the command.

Use SSH `cpanm` when:

* You're scripting an install (deploy hooks, automated setup).
* You need a specific version: `cpanm Module@1.234`.
* The cPanel UI times out on a slow-compiling module (rare, but `DBD::Pg` and `Crypt::OpenSSL::*` are known offenders).

## Common issues

<AccordionGroup>
  <Accordion title="Compile fails with 'Can't find header' or '.h: No such file or directory'">
    The module needs a C library that isn't installed. Most XS-based modules need `libssl-dev`, `libxml2-dev`, or similar at compile time. We install the most common ones server-wide; for an unusual one, open a ticket and we can install the dev package.
  </Accordion>

  <Accordion title="Module installs but my script can't find it">
    The script isn't loading the local Perl tree. Add the `use lib` line above, or shebang to `/usr/local/cpanel/3rdparty/bin/perl` which has the wrapper baked in.
  </Accordion>

  <Accordion title="DBD::mysql install hangs">
    `DBD::mysql` needs network access to the MySQL test server during build. Ours is firewalled in some configs. If the install hangs past 5 minutes, kill the cPanel page and re-run with `--notest` over SSH:

    ```bash theme={}
    cpanm --notest --local-lib=~/perl DBD::mysql
    ```
  </Accordion>
</AccordionGroup>

## Need a hand?

<CardGroup cols={2}>
  <Card title="Open a ticket" icon="life-ring" href="https://members.noxity.io/submitticket.php">
    Best for anything that needs an account check or a config change on our end.
  </Card>

  <Card title="Live chat" icon="messages" href="https://noxity.io/contact">
    Faster for quick questions during business hours.
  </Card>
</CardGroup>