# ImageMagick e ffmpeg no cPanel: o que você instala sozinho

Como separar, pela tela do painel, o que é extensão de PHP, o que é módulo PECL/Perl e o que é pacote do sistema, e o que responder ao dev quando aparece 'convert: command not found'.

> depende da camada. Extensão de PHP (como imagick) você liga sozinha em cPanel » Select PHP Version. ImageMagick, ffmpeg, Ghostscript e fontes são pacotes do sistema operacional: em hospedagem compartilhada, só o administrador instala, via WHM » Install Distro Packages ou root por SSH.

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

---

## Três camadas diferentes escondidas no mesmo pedido

O desenvolvedor do cliente manda uma linha: "o sistema precisa de ImageMagick". Ou pior, cola um log com `sh: convert: command not found` e `ffmpeg not found`. Parece um pedido só. São três coisas que vivem em lugares diferentes do servidor, com donos diferentes.

| Camada | Exemplos | Onde se resolve | Quem executa |
|---|---|---|---||
| Extensão de PHP | `imagick`, `intl`, `soap`, `zip`, `gd` | cPanel » Select PHP Version (ou MultiPHP) | você, na conta |
| Módulo PECL / Perl | PECL sem pacote pronto, `.pm` ausente | cPanel » PHP PECL / Perl Modules, quando habilitado; senão WHM » Module Installers | você ou o administrador |
| Pacote do sistema operacional | binário `convert`/`magick`, `ffmpeg`, `ghostscript`, fontes (`fontconfig`, famílias TTF) | WHM » Software » Install Distro Packages, ou gerenciador de pacotes via SSH como root | só o administrador do servidor |

O detalhe que trava a conversa: **`imagick` e ImageMagick não são a mesma coisa**. `imagick` é a extensão PHP que fala com a biblioteca; o ImageMagick em si é o pacote do sistema, que traz as bibliotecas e os binários `convert`/`magick`. Habilitar a extensão num servidor sem a biblioteca não funciona, e instalar a biblioteca não liga a extensão sozinha. Quando o dev diz "ImageMagick", pergunte qual dos dois ele chama: `exec('convert ...')` no código ou `new Imagick()`.

ffmpeg é mais simples de classificar e mais difícil de obter: não existe extensão PHP oficial equivalente. É binário do sistema, ponto. Todo código que usa ffmpeg chama um processo externo.

## Antes de abrir chamado, prove que o binário não existe

Boa parte dos pedidos morre aqui, porque o binário já está instalado e o problema é outro (PATH, `exec` desabilitado, `open_basedir`). Entre por SSH na conta ou use o Terminal do cPanel e rode:

```bash
# o binário existe e está no PATH do usuário?
command -v convert magick ffmpeg gs

# versão (confirma que executa, não só que o arquivo está lá)
convert -version
ffmpeg -version

# fontes instaladas no sistema
fc-list | wc -l
fc-list | grep -i dejavu
```

Se `command -v` não devolve nada, teste o caminho absoluto antes de concluir: `ls -l /usr/bin/convert /usr/local/bin/ffmpeg`. Em alguns ambientes o binário existe fora do PATH padrão do usuário, e basta o dev chamar pelo caminho completo.

Agora o lado do PHP, que é onde mora o segundo engano:

```bash
# extensões carregadas na versão de PHP da conta
php -m | grep -iE 'imagick|gd|exif'

# funções de execução externa desabilitadas?
php -i | grep -i disable_functions
```

Se `exec`, `shell_exec`, `proc_open` e `system` estão em `disable_functions`, o ffmpeg pode estar instalado e o código continuará vendo "not found" ou simplesmente nada. Esse é um problema de configuração de PHP, não de pacote. Vale o mesmo para scripts que rodam via cron com PATH enxuto: no cron, use caminho absoluto.

Um detalhe que economiza ida e volta: a versão de PHP do site pode ser diferente da versão do `php` da linha de comando. Confira em cPanel » Select PHP Version qual versão está ativa para o domínio e teste a extensão por um arquivo com `phpinfo()` ou por `php-cli` apontando o binário da versão certa.

## Extensão de PHP você liga sozinha em Select PHP Version

Extensão de PHP é autosserviço. Em **cPanel » Software » Select PHP Version**, marque a extensão, salve e revalide com `php -m` ou `phpinfo()`. É assim para `intl`, `soap`, `zip`, `exif`, `gd` e, quando o pacote existe no servidor, `imagick`.

Se a extensão não aparece na lista, ela não está disponível naquele servidor para aquela versão de PHP. Não insista na tela: isso vira pedido para o administrador, porque a instalação acontece no nível do sistema (EasyApache 4 ou pacote PECL compilado contra as bibliotecas de desenvolvimento).

A mesma lógica vale para os instaladores de módulo da conta (PHP PECL e Perl Modules, quando o provedor os expõe): eles instalam dentro do diretório da conta, mas a compilação depende de cabeçalhos e ferramentas de build do sistema. Sem a biblioteca de desenvolvimento presente, o build falha com erro de header ausente, e não há como resolver isso sem acesso de root: o caminho é abrir chamado pedindo o pacote `-devel` correspondente.

## O que só o administrador instala, e com qual ferramenta

Pacote de sistema operacional em servidor cPanel tem uma porta documentada: a interface **WHM » Software » Install Distro Packages**, que permite ao administrador pesquisar e instalar pacotes da distribuição a partir do próprio WHM, usando o gerenciador de pacotes do sistema ([documentação oficial do cPanel](https://docs.cpanel.net/whm/software/install-distro-packages/)). É acesso de root. Não existe equivalente no painel do usuário, e não é restrição comercial: é separação de privilégio, porque o pacote é compartilhado por todas as contas do servidor.

Três consequências práticas para você explicar ao cliente:

- **Fonte para PDF costuma ser pacote de sistema.** Fontes colocadas em `~/.fonts` ou `~/.local/share/fonts` são lidas pelo fontconfig do usuário depois de `fc-cache -f`, e podem funcionar para processos que rodam como a conta. O que não funciona é depender disso quando o processamento acontece em serviço que roda como outro usuário. Algumas bibliotecas aceitam caminho absoluto para o arquivo da fonte; essa costuma ser a saída que não depende de ninguém. Vale testar antes de pedir instalação.
- **ffmpeg costuma não estar nos repositórios base da família RHEL**, que é a base dos servidores cPanel. Instalar exige o administrador habilitar repositório de terceiro, decisão que tem custo de manutenção e superfície de atualização. A resposta pode legitimamente ser não.
- **Pacote instalado vale para o servidor inteiro.** Em compartilhado, na prática não se instala binário por conta. Se a resposta for sim, todas as contas passam a ter.

## Por que não compilar na pasta da conta nem rodar yum em paralelo

A gambiarra clássica é baixar o estático do ffmpeg para `~/bin` e apontar o código para lá. Funciona na demo e quebra depois, por motivos previsíveis: o binário não recebe atualização de segurança, ocupa a cota de disco da conta, depende de `exec` liberado, costuma ser pego por varredura de malware por ser executável não empacotado, e some em qualquer migração de conta. Compilar na conta é pior ainda: consome CPU e memória do ambiente compartilhado, quase sempre esbarra em limite de processo, e produz um binário ligado a bibliotecas que podem mudar na próxima atualização do sistema.

Do lado de quem tem root, a tentação é `dnf install` de qualquer repositório. Em servidor com cPanel isso é arriscado porque o gerenciador do painel mantém versões e exclusões próprias de pacotes críticos (Apache, PHP, MySQL, Perl). Repositório de terceiro com prioridade errada pode substituir um pacote gerenciado pelo painel e quebrar a atualização seguinte. Quando o pacote está disponível na distribuição, a rota pelo WHM » Install Distro Packages evita esse tipo de surpresa, porque usa o gerenciador do sistema a partir do próprio painel.

## Checklist para padronizar em vários sites

Rode isto sempre na mesma ordem. Leva poucos minutos por conta e evita chamado sem diagnóstico.

### Descobrir se o código chama binário externo ou classe PHP

Pergunte ao dev: o código chama `exec('convert')` / `exec('ffmpeg')` ou usa classe PHP (`Imagick`, `Gmagick`)? Chamada externa é pacote de sistema. Classe é extensão de PHP, que ainda assim pode depender da biblioteca do sistema.

### Verificar o que já existe no servidor e anotar a saída

`command -v convert magick ffmpeg gs`, `php -m`, `fc-list | wc -l`. Anote a saída: ela vai no chamado.

### Checar disable_functions, open_basedir e limite de tempo

`disable_functions`, `open_basedir`, limite de memória e `max_execution_time`. Processamento de vídeo estoura tempo muito antes de estourar pacote.

### Resolver o que é seu: extensão e fonte

Extensão disponível na lista: ligue em Select PHP Version e valide. Fonte: coloque o `.ttf` em `~/.local/share/fonts`, rode `fc-cache -f` e confira com `fc-list | grep`; se o processo não enxergar, aponte o caminho absoluto do arquivo no código.

### Abrir chamado com os seis itens que evitam pergunta de volta

Um chamado útil tem: domínio, versão de PHP ativa, nome exato do pacote pretendido, a saída de `command -v`, a mensagem literal do erro e para que serve (miniatura, PDF, conversão de vídeo). Chamado com "preciso de ImageMagick" volta com pergunta; chamado com esses seis itens volta com decisão.

### Registrar o que aquele servidor tem e reaproveitar

Se o servidor tem `convert` e não tem `ffmpeg`, isso vale para todos os seus sites naquele servidor. Anote uma vez, reaproveite em todos os orçamentos seguintes.

## A frase pronta para quando o pedido é pacote de sistema

Quando a verificação mostra que o pedido é pacote de sistema e o servidor é compartilhado, a resposta honesta não depende de você. Mande isto, adaptando o nome do pacote:

> **** O que você pediu não é extensão de PHP, é pacote do sistema operacional. Em hospedagem compartilhada, só o administrador do servidor instala, por WHM » Software » Install Distro Packages ou pelo gerenciador de pacotes como root, e a instalação vale para todas as contas do servidor. Já verifiquei na conta: `command -v convert magick ffmpeg` não retorna o binário e `php -m` não lista a extensão correspondente. Abri a solicitação com essa saída. Se a resposta for negativa, as alternativas são: usar uma biblioteca em PHP puro para o mesmo efeito, usar um serviço externo de processamento via API, ou mover a aplicação para um VPS com acesso root.

E uma segunda frase, para o cliente final, sem jargão:

> **** O site precisa de um programa instalado no servidor, não dentro do site. Em plano compartilhado, esse programa é do servidor inteiro e quem instala é a equipe de infraestrutura. Já pedimos. Se não for possível, a saída é trocar a forma como essa função é feita ou usar um servidor dedicado à sua aplicação.

Dizer "isso não depende de nós" com a verificação anexada não é passar o problema adiante. É entregar diagnóstico. O dev para de tentar instalar coisa no `~/bin`, o cliente entende por que existe VPS, e você não vende um plano que não resolve o caso.

