blog
Painéis

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.

JR · · 9 min de leitura · 1 tabela · 6 blocos de código

Resposta curta: 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.

Neste artigo
  1. O que a mensagem diz, palavra por palavra
  2. Por que este erro não é o mesmo que um erro 500 genérico
  3. Confirme o nome do módulo e o que o seu Perl enxerga antes de instalar
  4. Instalar pelo Perl Modules do cPanel
  5. Quando o painel não oferece Perl Modules: instalar em lib/ da própria conta
  6. Instalei e o erro continua: os quatro motivos
  7. Checklist para confirmar que o erro não volta

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:

  1. 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.
  2. 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.
  3. 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.

Do log à decisão de como instalar o móduloLeia a linha do error logcPanel, Métricas, ErrosComeça com Can't locate?Se não, veja a tabela de sintomasExtraia o caminho .pmTroque barras por dois-pontos duplosTem Perl Modules no painel?Software, Perl ModulesSim: instale pelo painelConfira na lista de instaladosNão: instale em perl5 do homeE aponte com use lib
Caminho de decisão entre ler o log e escolher a via de instalação.

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/).

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:

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, 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:

  1. 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).
  2. 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.
  3. 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.
  4. 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:

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.

Instalação manual em lib da própria contaBaixarTarball no metacpan.orgCriar pastasperl5/lib/perl5 no homeEnviarConteúdo de lib mantendo subpastasApontaruse lib antes dos useTestarRodar o script e reler o log
Sequência da instalação manual quando o painel não oferece Perl Modules.

Instalei e o erro continua: os quatro motivos

  1. 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";'.
  2. 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.
  3. Instalou outro módulo: DateTime e DateTime::Format::Strptime são distribuições diferentes. Instalar o pai não traz o filho.
  4. 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

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 (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.

Referências

  1. Documentação oficial (cpanel) — Perl Modules. Consultado em 2026-09-29.
Leia também