# Can't locate Modulo.pm in @INC: como resolver no cPanel

Como ler os três dados que a mensagem entrega, instalar o módulo certo pelo cPanel e provar que o interpretador passou a encontrá-lo.

> a linha `Can't locate Modulo.pm in @INC` diz que falta um módulo Perl, não que há erro de permissão ou shebang. Converta o caminho do arquivo (`DateTime/Format/Strptime.pm`) para o nome com `::`, instale em Software > Perl Modules no cPanel e confirme com uma linha de teste.

João Rizzon · 2026-10-02 · Painéis

---

## O que a mensagem diz, palavra por palavra

O erro aparece no error log do site, na saída de erro do cron (o e-mail que o cron envia ou o arquivo para onde você redirecionou a saída na linha do agendamento) ou direto na tela quando o script roda pelo terminal.

Para ler o log do site no cPanel, vá em **Métricas** e clique em **Erros**: a tela mostra as últimas entradas do error log do domínio. Se o erro for antigo e já tiver saído dessa tela, abra o **Gerenciador de Arquivos**, entre na pasta `logs` dentro do seu diretório home e procure o arquivo com o nome do domínio terminado em `-error_log` ou `error_log`; clique nele e use **Exibir** (View) para ler sem baixar.

Para o cron, abra **Trabalhos Cron** (*Cron Jobs*) no cPanel: o campo de e-mail no topo da página define para onde vai a saída de erro de cada tarefa. Se esse campo estiver vazio ou apontando para uma caixa que você não lê, preencha com um endereço seu e rode a tarefa de novo para receber a mensagem completa.

A forma típica do erro (exemplo fictício, só para destrinchar a sintaxe):

```
Can't locate DateTime/Format/Strptime.pm in @INC (you may need to install the DateTime::Format::Strptime module) (@INC contains: /home/usuario/perl5/lib/perl5/x86_64-linux-thread-multi /home/usuario/perl5/lib/perl5 /usr/local/lib64/perl5 /usr/local/share/perl5 /usr/lib64/perl5 /usr/share/perl5) at /home/usuario/public_html/cgi-bin/relatorio.pl line 8.
```

Três informações saem dessa linha, e as três importam:

- **O arquivo que faltou**: `DateTime/Format/Strptime.pm`. Troque as barras por `::` e você tem o nome do módulo como ele é publicado no CPAN: `DateTime::Format::Strptime`. É esse nome que você vai digitar no painel, não o caminho com barras.
- **Onde o Perl procurou**: tudo que está entre parênteses depois de `@INC contains:`. Se o diretório para onde você instalou o módulo não estiver nessa lista, o módulo pode estar instalado e ainda assim o script falha.
- **Quem pediu**: `relatorio.pl line 8`. Abra o arquivo nessa linha; lá está o `use` ou o `require` correspondente.

`@INC` é a lista de diretórios que o interpretador Perl percorre, na ordem, procurando o arquivo `.pm`. Nada mais que isso. Não é permissão, não é usuário, não é PATH do shell.

## Por que este erro não é o mesmo que um erro 500 genérico

Vale separar, porque os três problemas mais comuns em script CGI têm sintomas parecidos no navegador e procedimentos completamente diferentes.

| Sintoma no log | Causa provável | O que resolve |
|---|---|---||
| `Can't locate X.pm in @INC` | Módulo Perl ausente nos diretórios de busca | Instalar o módulo (este artigo) |
| `Premature end of script headers` | Script não imprimiu `Content-Type` antes do corpo | Corrigir a saída do script |
| `/usr/bin/perl: bad interpreter` ou `No such file or directory` na primeira linha | Shebang errado, ou arquivo salvo com quebra de linha do Windows (CRLF) | Ajustar o shebang e reenviar em modo ASCII |
| `Permission denied` | Arquivo sem bit de execução | `chmod 755` no `.pl` |

Se o log mostra `Can't locate`, instalar módulo é o caminho. Mexer em permissão ou shebang não muda nada nesse caso, e você gasta a tarde.

## Confirme o nome do módulo e o que o seu Perl enxerga antes de instalar

Se a sua conta tem acesso SSH, duas linhas resolvem a conferência. Se não tem, pule para a seção do painel; nenhum dos comandos é obrigatório.

Primeiro, veja a lista de diretórios do seu Perl, já quebrada em uma por linha:

```
perl -e 'print "$_\n" for @INC;'
```

O resultado esperado é uma lista de caminhos, um por linha. Compare com a lista que apareceu no erro: se o seu script roda pelo servidor web e você está testando pelo SSH, podem ser interpretadores diferentes, com `@INC` diferentes. Guarde essa diferença, ela explica metade dos casos de "instalei e continua dando erro".

Depois, pergunte ao Perl se ele acha o módulo:

```
perl -e 'use DateTime::Format::Strptime; print "ok\n";'
```

Dois resultados possíveis. Se imprimir `ok`, o módulo está instalado e visível para esse interpretador. Se repetir o `Can't locate`, está faltando mesmo. Troque `DateTime::Format::Strptime` pelo nome que você extraiu do seu log.

## Instalar pelo Perl Modules do cPanel

A documentação oficial do cPanel descreve a interface **Perl Modules**, em *Software* no menu principal, como o lugar onde o usuário instala e gerencia módulos Perl na própria conta ([docs.cpanel.net/cpanel/software/perl-modules/](https://docs.cpanel.net/cpanel/software/perl-modules/)).

### Onde fica a interface Perl Modules no painel

No cPanel, vá em **Software** e clique em **Perl Modules**. Se o ícone não existir no seu painel, o recurso não está habilitado para a conta; vá para a seção seguinte, que trata exatamente desse caso.

### Digite o nome com :: , não o caminho com barras

A interface traz um campo para digitar o nome do módulo e um botão de instalação. Digite o nome com `::`, do jeito que você converteu a partir do caminho do erro: `DateTime::Format::Strptime`, e não `DateTime/Format/Strptime.pm`.

A documentação do cPanel também descreve a busca por módulos disponíveis e a listagem dos módulos já instalados na conta, com a opção de reinstalar ou remover. Use a lista de instalados depois da operação: o módulo precisa aparecer lá.

### Como ler a saída da instalação e identificar a dependência que quebrou

A instalação de módulo Perl compila e testa dependências, então a saída é longa e pode demorar. Dois finais interessam:

- Terminou com sucesso: o módulo passa a constar na lista de instalados.
- Falhou em um teste de dependência: a saída mostra qual dependência quebrou. Anote o nome dela e tente instalá-la primeiro, separadamente. Módulos que exigem biblioteca de sistema (compilador, headers de C) podem simplesmente não instalar em conta compartilhada; nesse caso a alternativa costuma ser um módulo equivalente em Perl puro.

### Confirme a instalação com uma linha de teste

Rode de novo:

```
perl -e 'use DateTime::Format::Strptime; print "ok\n";'
```

Saída `ok` significa que o interpretador encontrou o arquivo. Só então volte ao script.

## Quando o painel não oferece Perl Modules: instalar em lib/ da própria conta

Sem a interface, o caminho é instalar o módulo dentro do seu home e dizer ao script onde procurar. A ideia é simples: você cria um diretório, coloca o `.pm` lá dentro respeitando a estrutura de pastas, e acrescenta esse diretório ao `@INC` do script.

### Monte a estrutura de pastas

Antes de montar pasta nenhuma, você precisa ter os arquivos em mãos: eles não aparecem sozinhos. Abra [metacpan.org](https://metacpan.org/), busque o nome do módulo com `::` (o mesmo que você extraiu do erro), e na página da distribuição clique em **Download** para baixar o tarball (um arquivo `.tar.gz`). Guarde-o no seu computador.

O nome do arquivo no erro já é o caminho. `DateTime/Format/Strptime.pm` precisa virar, dentro do seu diretório de bibliotecas:

```
/home/usuario/perl5/lib/perl5/DateTime/Format/Strptime.pm
```

Passo a passo para chegar lá sem terminal:

- Descompacte o `.tar.gz` no seu computador. Dentro dele existe uma pasta `lib`; é ali que mora a árvore de diretórios do módulo, já no formato certo (`lib/DateTime/Format/Strptime.pm`).
- No cPanel, abra o **Gerenciador de Arquivos** e crie, a partir do seu diretório home, as pastas `perl5`, depois `lib` e depois `perl5` dentro dela, usando o botão **+ Pasta** (*New Folder*). Você vai terminar com `/home/usuario/perl5/lib/perl5`.
- Entre em `/home/usuario/perl5/lib/perl5`, clique em **Carregar** (*Upload*) e envie o conteúdo de dentro da pasta `lib` do pacote, mantendo a mesma estrutura de subpastas. O Gerenciador de Arquivos envia um arquivo por vez: crie as pastas `DateTime` e `DateTime/Format` manualmente e envie o `.pm` para dentro da última.
- Se a sua conta tem SSH, o atalho é enviar o `.tar.gz` para o home pelo **Carregar** e rodar `tar -xzf nome-do-pacote.tar.gz` no terminal, depois copiar a pasta `lib` inteira com `cp -r nome-do-pacote/lib/* ~/perl5/lib/perl5/`. O resultado esperado é nenhuma mensagem na tela e o arquivo `.pm` visível em `~/perl5/lib/perl5/DateTime/Format/`.

Módulo que vem distribuído com vários arquivos precisa de todos eles, não só do `.pm` que apareceu no erro. Por isso essa via funciona bem para módulos pequenos, em Perl puro, e mal para módulos que compilam código C.

### Aponte o @INC no próprio script

No topo do `.pl`, antes dos `use` que dependem do módulo, acrescente:

```perl
use lib '/home/usuario/perl5/lib/perl5';
```

Troque `usuario` pelo nome real da sua conta. `use lib` insere o diretório no começo do `@INC`, então ele passa a ser consultado antes dos caminhos do sistema. Como `use` é resolvido em tempo de compilação, a linha precisa vir **antes** do `use` do módulo que estava faltando.

Risco e volta atrás: você está editando um script em produção. Baixe uma cópia do `.pl` antes de alterar e guarde fora do servidor. Se algo quebrar, suba a cópia de volta e o site volta ao estado anterior em segundos. O mesmo vale para a instalação por painel: ela não altera seus arquivos, mas uma dependência atualizada pode mudar o comportamento de outro script que usava a versão antiga.

## Instalei e o erro continua: os quatro motivos

- **Interpretador diferente**: o script roda com o Perl apontado no shebang, que pode não ser o mesmo que responde ao comando `perl` no SSH. Compare a primeira linha do `.pl` com a saída de `which perl`. Se forem caminhos diferentes, teste com o caminho do shebang: `/usr/bin/perl -e 'use SeuModulo; print "ok\n";'`.
- **Nome com maiúscula errada**: `Net::SSLeay` não é `Net::ssleay`. O arquivo no disco é case-sensitive. Copie do log, não digite de memória.
- **Instalou outro módulo**: `DateTime` e `DateTime::Format::Strptime` são distribuições diferentes. Instalar o pai não traz o filho.
- **Diretório fora do `@INC`**: o módulo está lá, mas em um caminho que não aparece na lista do erro. Confira rodando de novo o `perl -e 'print "$_\n" for @INC;'` e veja se o diretório onde o arquivo foi parar consta na saída. Se não consta, use `use lib` como descrito acima.

Um detalhe que economiza tempo: depois de instalar, leia **a linha inteira do novo erro**, se houver. É comum o `Can't locate` mudar de módulo, porque o primeiro foi resolvido e agora falta uma dependência do próprio script. Cada rodada resolve um nome. Não é regressão, é progresso.

## Checklist para confirmar que o erro não volta

- Copiei a linha literal do log e extraí o caminho `.pm`.
- Converti para o nome com `::`.
- Anotei a lista de `@INC` que apareceu no erro.
- Instalei pelo **Perl Modules** do cPanel (*Software* > *Perl Modules*) e vi o módulo na lista de instalados.
- Rodei `perl -e 'use Modulo; print "ok\n";'` e recebi `ok`.
- Executei o script de verdade, pelo mesmo caminho que falhava (navegador ou cron), e confirmei no error log que a linha `Can't locate` não voltou.

Se o módulo não instala por exigir biblioteca de sistema, essa é a hora de pedir ajuda ao suporte da hospedagem com a saída do erro de compilação em mãos: é uma decisão do servidor, não da sua conta. E se o novo erro no log não começa com `Can't locate`, você saiu deste procedimento e entrou em outro; volte à tabela da segunda seção.

**Fonte consultada:** documentação oficial do cPanel, [Perl Modules](https://docs.cpanel.net/cpanel/software/perl-modules/) (consultada em 29/09/2026). Os trechos de log e os nomes de módulo usados aqui são exemplos ilustrativos, não medições.

