# gem install: Permission denied sem root no cPanel

Onde o cPanel guarda as gems do ambiente Ruby, como instalar sem root e por que a falha de extensão nativa é o caso em que a solução pode não estar nas suas mãos.

> o `Permission denied` em `/usr/lib/ruby/gems` acontece porque o `gem install` tentou gravar numa pasta do sistema. Há três saídas sem root: a interface RubyGems do cPanel, a flag `--user-install` e o Bundler com `path` local no projeto.

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

---

## Permission denied e falha de compilação são dois erros diferentes

Você criou o ambiente em **Setup Ruby App** (ou **Application Manager**, dependendo da versão do cPanel), abriu o Terminal e rodou `gem install mysql2`. A resposta não foi um log de aplicação quebrada, foi isto:

```
ERROR:  While executing gem ... (Gem::FilePermissionError)
    You don't have write permissions for the /usr/lib/ruby/gems/3.0.0 directory.
```

Ou, em outra variação:

```
ERROR:  Error installing mysql2:
    ERROR: Failed to build gem native extension.
```

São dois problemas diferentes com a mesma aparência. O primeiro é de **destino**: o gem tentou escrever numa pasta do sistema, que pertence ao root, e sua conta não escreve lá. Isso você resolve sozinho. O segundo é de **compilação**: a gem precisa de uma biblioteca de sistema que não está instalada, e isso não se resolve dentro da conta, por nenhum truque de caminho.

Saber em qual dos dois você caiu é o primeiro passo. Leia a mensagem inteira, não só a última linha.

## Por que o gem do terminal grava na pasta do sistema

Quando você cria uma aplicação Ruby pelo cPanel, o painel monta um ambiente isolado dentro da sua conta, com um interpretador e um diretório de gems próprios daquele aplicativo. O cPanel exibe, na tela do aplicativo, um comando de ativação (o botão de copiar fica ao lado do caminho). É algo no formato `source /home/USUARIO/rubyvenv/APP/VERSAO/bin/activate && ...`, com os valores da sua conta.

O Terminal do cPanel, porém, abre uma sessão limpa. Sem rodar esse comando de ativação, o `gem` que o shell encontra é o do sistema, e o destino padrão dele é a pasta de gems do sistema. Daí o `Permission denied`.

Na prática, existem três destinos possíveis, e vale saber distinguir:

| Destino | Quando é usado | Você escreve nele |
|---|---|---||
| Pasta de gems do sistema (`/usr/lib/ruby/gems/...`) | `gem install` sem ambiente ativado e sem flag | Não |
| Pasta de gems do usuário (`~/.gem/...`) | `gem install --user-install` | Sim |
| Pasta de gems do ambiente criado no cPanel | Depois de rodar o comando de ativação que o painel mostra | Sim |

O terceiro é o que a sua aplicação de fato enxerga quando o Phusion Passenger, o componente do servidor que carrega e executa sua aplicação Ruby, a coloca no ar. Instalar no segundo resolve o erro de permissão, mas pode não resolver o erro da aplicação, porque são coleções diferentes. Guarde essa distinção: ela explica a maioria dos casos de "instalei e continua dizendo que a gem não existe".

## Instalar pela interface RubyGems do cPanel, sem terminal

Se a ideia é só instalar uma gem no ambiente da aplicação, o cPanel tem uma tela para isso. A [documentação oficial da interface RubyGems](https://docs.cpanel.net/cpanel/software/rubygems/) indica que ela fica em **cPanel » Software » RubyGems**. É por ali que você instala e remove gems da sua conta, sem root.

### Passo a passo na tela RubyGems

- Entre no cPanel e, na busca do topo, digite `RubyGems`. Clique no ícone.
- Em **Install a New Gem** (em português, algo como "Instalar uma nova gem"), preencha o campo **Gem Name** com o nome exato da gem (`nokogiri`, por exemplo) e clique em **Install**.
- Aguarde o retorno da tela. A gem passa a aparecer na tabela **Installed Gems** ("Gems instaladas"), com nome e versão.
- Para remover, clique no ícone de lixeira (**Uninstall**) na linha da gem, dentro dessa mesma tabela.

Os rótulos acima são os da interface em inglês e mudam conforme a versão do cPanel e o idioma do painel. Se o seu painel mostrar nomes diferentes, procure o campo de texto para o nome da gem e a lista com as gems já instaladas: a sequência é a mesma.

É o caminho com menos chance de errar o destino, porque o painel já sabe onde fica a instalação da sua conta. A limitação é a mesma do terminal: algumas gems trazem extensão nativa, ou seja, um pedaço escrito em C que precisa ser compilado no servidor contra uma biblioteca do sistema. Se essa biblioteca não existe na máquina, a instalação falha aqui também.

## Duas formas de instalar pelo terminal sem escrever no root

Quando você precisa do terminal (para ver o erro completo, por exemplo), existem duas formas de não escrever na pasta do sistema.

### Ative o ambiente da aplicação antes de qualquer gem install

Copie o comando de ativação que o cPanel mostra na tela do seu aplicativo Ruby e cole no Terminal. Depois confirme onde você está:

```
gem env home
```

Resultado esperado: um caminho dentro de `/home/SEU_USUARIO/`. Se aparecer `/usr/lib/...`, o ambiente não foi ativado e qualquer `gem install` vai falhar de novo.

Com o ambiente ativo, instale normalmente:

```
gem install nokogiri
```

### Force o destino com --user-install

Se você só quer uma ferramenta de linha de comando, sem vínculo com a aplicação:

```
gem install --user-install nome_da_gem
```

A flag `--user-install` manda o RubyGems gravar no diretório de gems do seu usuário, em vez do diretório do sistema. Não precisa de root. Confira com:

```
gem list nome_da_gem
```

Resultado esperado: o nome da gem e a versão. Se não aparecer, verifique se você não trocou de shell no meio do caminho.

### Como desfazer a instalação na pasta do usuário

```
gem uninstall nome_da_gem
```

Se a gem foi instalada nos dois lugares, o comando pergunta qual remover. Leia as opções antes de responder.

## Bundler instalando em vendor/bundle dentro da conta

Aplicação Rails ou Sinatra não se resolve com `gem install` avulso: o `Gemfile` manda. O problema é que o `bundle install` também tenta o destino padrão do Ruby, e aí volta o `Permission denied`.

A solução é dizer ao Bundler, naquele projeto, onde instalar. Dentro da pasta da aplicação:

```
bundle config set --local path 'vendor/bundle'
bundle install
```

A primeira linha grava a preferência em `.bundle/config`, dentro do próprio projeto. A partir daí, as gems vão para `vendor/bundle`, uma pasta da sua conta. O `--local` é importante: ele limita a configuração a este projeto, sem mexer em nada global.

Resultado esperado da segunda linha: uma lista de gems sendo buscadas e instaladas, terminando em `Bundle complete!` com a contagem de gems. Se terminar em erro de compilação, pule para a próxima seção.

Para rodar comandos usando exatamente essas gems:

```
bundle exec rails -v
```

### Como desfazer o path local do Bundler

```
bundle config unset --local path
```

Isso remove a linha do `.bundle/config`. A pasta `vendor/bundle` continua no disco; apague manualmente se quiser liberar espaço, depois de confirmar que a aplicação não depende mais dela. Antes de apagar qualquer pasta, faça backup da conta pelo **cPanel » Arquivos » Backup**. É mais rápido baixar um backup do que reconstruir um `vendor/bundle` grande numa conexão ruim.

## Quando falta biblioteca do sistema e nenhum truque de caminho resolve

Algumas gems não são Ruby puro: elas compilam código C contra uma biblioteca do sistema operacional. `mysql2` precisa do cliente MySQL, `pg` precisa do cliente PostgreSQL, `rmagick` precisa do ImageMagick, e todas precisam dos arquivos de cabeçalho correspondentes: os arquivos `.h` que descrevem ao compilador como falar com aquela biblioteca, distribuídos em pacotes com sufixo `-dev` ou `-devel`.

Esses arquivos ficam em diretórios do sistema. Não existe `--user-install` que os crie. Se não estão no servidor, a compilação falha, e falha igual pela interface RubyGems, pelo terminal e pelo Bundler.

Como reconhecer no log:

| Trecho na saída | O que está faltando |
|---|---||
| `mysql_config` not found / `libmysqlclient` | cliente MySQL e headers |
| `pg_config` executable not found | cliente PostgreSQL e headers |
| `Can't find Magick-config` ou `MagickWand.h` | ImageMagick e headers |
| `You have to install development tools first` | compilador C e headers do Ruby |

O que fazer, em ordem:

- **Verifique se existe alternativa em Ruby puro.** Para MySQL, há drivers que não compilam extensão. Isso é contorno, não correção: o erro de compilação continua existindo, você só deixa de depender dele. Quando dá para trocar a gem, é o caminho mais rápido e não depende de ninguém.
- **Leia o log inteiro.** O arquivo `mkmf.log` citado na mensagem de erro aponta a biblioteca exata que faltou. Copie esse nome.
- **Abra um chamado com o administrador do servidor** informando a gem, a versão do Ruby e o nome da biblioteca do passo 2.

E o ponto que costuma ser omitido: **isso não é limitação de plano**. Trocar para um plano maior não instala `libpq-dev` em lugar nenhum. O que resolve é alguém com root instalar o pacote no servidor, ou você migrar para um ambiente onde você mesmo tenha root, como um VPS. Se um suporte responder a esse erro oferecendo upgrade sem explicar qual pacote será instalado, pergunte qual pacote será instalado.

## Checklist antes de abrir chamado

Antes de pedir ajuda, reúna estas respostas. Com elas, quem for te atender resolve em uma mensagem, não em cinco.

- Onde o Ruby está gravando: saída de `gem env home`.
- Qual Ruby está ativo: saída de `ruby -v`.
- A mensagem de erro completa, não só a última linha.
- Se o erro cita `/usr/lib/ruby/gems`, é destino. Ative o ambiente ou use `--user-install`.
- Se o erro cita `Failed to build gem native extension`, é biblioteca de sistema. Procure o `mkmf.log`.
- Se a aplicação continua dizendo que a gem não existe mesmo depois de instalada: você instalou numa coleção e a aplicação lê outra. Reinstale com o ambiente do cPanel ativado, ou pela interface RubyGems.

Depois de qualquer instalação que mexa no `Gemfile.lock`, reinicie a aplicação pelo botão correspondente na tela do Setup Ruby App. Sem reiniciar, o processo antigo continua rodando com o conjunto de gems antigo, e você vai debugar um erro que já não existe.

