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.

Resposta curta: 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.
Neste artigo
- Permission denied e falha de compilação são dois erros diferentes
- Por que o gem do terminal grava na pasta do sistema
- Instalar pela interface RubyGems do cPanel, sem terminal
- Duas formas de instalar pelo terminal sem escrever no root
- Bundler instalando em vendor/bundle dentro da conta
- Quando falta biblioteca do sistema e nenhum truque de caminho resolve
- Checklist antes de abrir chamado
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 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.logcitado 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 omkmf.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.
Referências
- Documentação oficial (cpanel) — RubyGems (cPanel). Consultado em 2026-10-09.