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

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

João Rizzon · 2026-11-07 · Painéis

---

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](https://docs.cpanel.net/knowledge-base/web-services/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:

- 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`.
- 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:

```bash
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

```bash
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

```bash
/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

```bash
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:

```bash
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:

```bash
/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`.

```bash
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:

```bash
/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:

```bash
/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:

```bash
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:

```bash
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.

