blog
Painéis

Instalar o Composer no cPanel sem root

Passo a passo documental, baseado na documentação oficial do cPanel, para baixar o composer.phar, achar o binário PHP certo e sobreviver ao erro de memória.

JR · · 8 min de leitura · 2 tabelas · 11 blocos de código

Resposta curta: no cPanel sem root, o Composer é instalado como arquivo dentro da própria conta: baixe o `composer.phar` pelo Terminal e execute-o sempre com o caminho completo do binário PHP que serve o site (ex.: `/opt/cpanel/ea-php82/root/usr/bin/php`), nunca com o `php` genérico do shell.

Neste artigo
  1. O backup da vendor e do composer.lock que evita a dor de cabeça
  2. Abrir o Terminal do cPanel
  3. Instalar o composer.phar dentro da própria conta
  4. Descobrir qual PHP realmente serve o seu site
  5. Rodar o composer install na pasta onde está o composer.json
  6. Quando a instalação morre no meio por falta de memória
  7. Seis erros comuns no Composer do cPanel e o que cada um significa
  8. Criar um alias para não digitar o caminho completo toda vez

Instalar o Composer em uma conta cPanel não é o mesmo que instalar no seu notebook. A documentação genérica manda rodar o instalador e mover o binário para /usr/local/bin, o que exige root. Em hospedagem compartilhada você não tem root, não tem PATH global e, pior, o php que o shell responde quase nunca é o mesmo PHP que serve o seu site.

Este guia é documental. Nada aqui foi medido por nós: o procedimento segue a documentação oficial do cPanel sobre configuração do PHP Composer (How to set up PHP Composer, consultada em 31/10/2026). Todos os caminhos de pasta e de binário que aparecem abaixo são exemplos. O seu provavelmente é outro. Confira cada um na tela antes de executar.

O backup da vendor e do composer.lock que evita a dor de cabeça

O composer install instala o que falta na pasta vendor e respeita o composer.lock, que é o arquivo que registra a versão exata de cada dependência. Com o lock presente e coerente com o composer.json, ele não apaga a vendor inteira nem sobe versões. Quem altera o lock e atualiza bibliotecas é o composer update.

Mesmo assim o backup vale: um install interrompido no meio (falta de memória, queda de conexão) deixa a vendor incompleta, e basta um update digitado por engano para o site quebrar com erro de classe não encontrada ou de método removido.

Faça duas coisas antes de rodar qualquer coisa:

  1. No Gerenciador de Arquivos do cPanel, entre na pasta do projeto, selecione a pasta vendor e o arquivo composer.lock, clique em Compress e gere um .zip dentro da mesma pasta. Nome sugerido: backup-vendor-lock.zip.
  2. Se o site é WordPress ou se o projeto inteiro é pequeno, gere também um backup completo do diretório em cPanel > Backup > Download a Home Directory Backup, ou um backup parcial da pasta.

Caminho de volta: se algo quebrar, apague a pasta vendor criada pelo Composer, extraia o backup-vendor-lock.zip no mesmo lugar e confirme que o composer.lock voltou com a data antiga. O site volta ao estado anterior sem precisar reinstalar nada.

Abrir o Terminal do cPanel

No painel, procure por Terminal, normalmente na seção Advanced. Se o ícone não existe, o provedor desabilitou o recurso para a conta e o caminho é acesso SSH ou um pedido ao suporte. A documentação do cPanel descreve o uso do Composer justamente a partir de uma sessão de shell da conta.

Ao abrir, você cai no diretório inicial, algo como /home/usuario. Confirme com:

pwd

O resultado esperado é o caminho da sua home. Guarde esse caminho: ele é o prefixo de tudo que vem depois.

Instalar o composer.phar dentro da própria conta

Sem root, o Composer vai viver como um arquivo dentro da sua home, não como comando global. A documentação oficial do cPanel orienta exatamente isso: baixar o instalador, executá-lo e usar o composer.phar resultante.

Antes de digitar qualquer coisa aqui, pule para a seção Descobrir qual PHP realmente serve o seu site, mais abaixo, e volte com o caminho completo do binário anotado. A ordem importa: se você instalar o Composer com o php genérico do shell, pode baixar uma versão antiga do instalador e só descobrir o problema horas depois, com a vendor já montada errada. Nos exemplos abaixo o caminho /opt/cpanel/ea-php82/root/usr/bin/php é só ilustrativo; troque pelo seu.

Baixar e rodar o instalador com o binário PHP do site

cd ~
curl -sS https://getcomposer.org/installer -o composer-setup.php
/opt/cpanel/ea-php82/root/usr/bin/php composer-setup.php

Linha a linha: cd ~ volta para a home; curl baixa o instalador oficial e salva como composer-setup.php; a terceira linha executa o instalador com o binário PHP do seu site, não com o php do shell. O resultado esperado é uma mensagem de sucesso informando a versão instalada e o nome do arquivo gerado, composer.phar, na pasta atual.

Conferir se o composer.phar responde

/opt/cpanel/ea-php82/root/usr/bin/php ~/composer.phar --version

Saída esperada: uma linha começando com Composer version. Se aparecer erro de versão de PHP incompatível, pare aqui e confirme que o caminho que você usou é mesmo o do binário associado ao domínio no painel, e não o php do shell.

Apagar o composer-setup.php depois da instalação

rm ~/composer-setup.php

Descobrir qual PHP realmente serve o seu site

Este é o passo que a documentação de desktop ignora e que causa a maior parte dos erros. O php do shell costuma ser uma versão antiga definida pelo sistema. O seu site roda sob a versão escolhida no MultiPHP Manager ou no Select PHP Version do cPanel, e os dois podem ser diferentes. Instalar dependências com o PHP errado gera um vendor incompatível com o que o site executa.

Ver no painel a versão de PHP associada ao domínio

No cPanel, abra MultiPHP Manager (ou Select PHP Version, dependendo do provedor) e anote a versão associada ao domínio do projeto. Exemplo: ea-php82.

Localizar o caminho do binário PHP correspondente

No Terminal, liste os binários disponíveis:

ls /opt/cpanel/ | grep php
ls /opt/alt/ 2>/dev/null | grep php
ls /usr/local/lsws/ 2>/dev/null | grep lsphp

O primeiro comando lista apenas os pacotes EasyApache (ea-php74, ea-php82 e similares). O segundo lista os pacotes CloudLinux alt-php, que ficam em outro diretório e aparecem como php81, php82. O terceiro só retorna algo se o servidor usa LiteSpeed. Os nomes de caminho abaixo são exemplos de formato, não garantia do que existe no seu servidor:

Stack Caminho de exemplo do binário Onde confirmar
EasyApache 4 /opt/cpanel/ea-php82/root/usr/bin/php MultiPHP Manager
CloudLinux alt-php /opt/alt/php81/usr/bin/php Select PHP Version
LiteSpeed /usr/local/lsws/lsphp82/bin/lsphp Painel do provedor
PHP do shell /usr/bin/php which php

Valide o candidato antes de usar:

/opt/cpanel/ea-php82/root/usr/bin/php -v

Saída esperada: a versão que você anotou no painel. Se não bater, tente outro caminho da lista. Compare também com a saída de which php para entender o quanto o shell estava te enganando.

Rodar o composer install na pasta onde está o composer.json

O Composer precisa ser executado no diretório onde está o composer.json. Em WordPress com dependências próprias, isso costuma ser a raiz do site ou a pasta do plugin/tema. Em projetos Laravel ou similares, é a raiz do repositório, normalmente fora de public_html.

cd ~/caminho/do/projeto
ls composer.json

Se o ls responder composer.json, você está no lugar certo. Se responder que o arquivo não existe, você está na pasta errada e o Composer vai criar lixo onde não deve.

Agora o comando completo, com o binário PHP explícito:

/opt/cpanel/ea-php82/root/usr/bin/php ~/composer.phar install

O que esperar: uma lista de pacotes sendo baixados, a frase sobre geração do autoload e um prompt de volta sem mensagem em vermelho. A pasta vendor passa a existir com dezenas ou centenas de subpastas.

Para ambiente de produção, prefira:

/opt/cpanel/ea-php82/root/usr/bin/php ~/composer.phar install --no-dev --optimize-autoloader

O --no-dev pula as dependências de desenvolvimento (ferramentas de teste, debug, linters), que não servem para nada em um site no ar e ocupam memória e disco durante a instalação.

Quando a instalação morre no meio por falta de memória

O sintoma típico é a saída parar de repente com Allowed memory size of X bytes exhausted ou, pior, o processo ser encerrado sem mensagem nenhuma, deixando o vendor pela metade.

Primeira tentativa, na ordem:

COMPOSER_MEMORY_LIMIT=-1 /opt/cpanel/ea-php82/root/usr/bin/php ~/composer.phar install --no-dev

O COMPOSER_MEMORY_LIMIT=-1 instrui o Composer a não impor limite de memória ao processo PHP. Ele vale só para esse comando, não altera o php.ini nem afeta o site.

Se mesmo assim o processo morrer, o teto não é do PHP. Em conta compartilhada existe um limite de memória por conta, aplicado pelo sistema, que derruba o processo antes de qualquer mensagem do PHP. Esse cenário, o diagnóstico de qual camada está cortando e o que fazer depois estão no artigo Composer sem memória no cPanel: PHP, binário ou cgroup, escrito para nível avançado. Não vale repetir aqui: se você chegou neste ponto, é lá que o fio continua.

Uma saída intermediária que resolve muitos casos sem tocar em limite nenhum: rodar o composer install na sua máquina local, com o mesmo composer.lock, e enviar a pasta vendor pronta por FTP ou upload de .zip no Gerenciador de Arquivos. Funciona porque o install com lock presente não resolve dependências, apenas reproduz as versões já travadas. Exige que a versão de PHP local seja compatível com a do servidor.

Seis erros comuns no Composer do cPanel e o que cada um significa

Mensagem Causa provável O que fazer
composer: command not found Você chamou composer sem o binário PHP e sem o caminho do .phar Use /opt/cpanel/ea-php82/root/usr/bin/php ~/composer.phar
requires php ^8.1 but your php version is 7.4 Binário PHP errado, o do shell Volte para a seção do MultiPHP Manager e use o caminho correto
Allowed memory size exhausted Limite de memória do PHP COMPOSER_MEMORY_LIMIT=-1 mais --no-dev
Could not find a matching version composer.json pede pacote incompatível com o PHP em uso Confira a versão do binário e o requisito do pacote
Your lock file does not contain a compatible set of packages O lock foi gerado em outra versão de PHP Regenere o lock em ambiente compatível, com backup antes
Processo encerra sem mensagem Limite do sistema, fora do PHP Pré-instalar o vendor localmente ou seguir o postmortem avançado

Criar um alias para não digitar o caminho completo toda vez

Digitar o caminho completo do PHP toda vez é desconfortável. Um alias na sua sessão resolve, sem alterar nada do servidor:

alias composer='/opt/cpanel/ea-php82/root/usr/bin/php ~/composer.phar'

Esse alias vale até você fechar o Terminal. Para torná-lo permanente, adicione a mesma linha ao final do arquivo ~/.bashrc pelo Gerenciador de Arquivos (ative Show Hidden Files nas configurações para enxergá-lo). Teste em uma nova sessão com composer --version.

Troque o caminho do exemplo pelo que você validou com php -v. E sempre que o provedor mudar a versão de PHP do domínio, o alias precisa ser atualizado, senão você volta a instalar dependências com o PHP errado sem perceber.

Referências

  1. Documentação oficial (cpanel) — How to set up PHP Composer. Consultado em 2026-10-31.
Leia também