Alisson's Notes

Pesquisar

SearchSearch

direnv

17 de set. de 2026Leitura de 3 min

direnv

Sobre

direnv é uma extensão de shell que carrega e descarrega variáveis de ambiente automaticamente conforme o diretório atual, evitando o acúmulo de configurações no ~/.profile. É compilado como um executável estático único, o que o torna rápido o suficiente para ser imperceptível a cada prompt, e é agnóstico de linguagem. Licença MIT, mantido por @zimbatm e contribuidores.

Funcionamento

Antes de cada prompt, o direnv verifica a existência de um arquivo .envrc (e, opcionalmente, .env) no diretório atual e nos diretórios pais. Se o arquivo existir e estiver autorizado (via direnv allow), ele é carregado em um sub-shell bash e todas as variáveis exportadas são capturadas e disponibilizadas no shell atual. Ao sair do diretório, as variáveis são descarregadas automaticamente.

Suporta hooks para os shells mais comuns: bash, zsh, tcsh, fish, elvish, powershell, murex e nushell.

$ mkdir ~/my-project && cd ~/my-project
$ echo ${FOO-nope}
nope

$ echo export FOO=foo > .envrc
.envrc is not allowed

$ direnv allow .
direnv: reloading
direnv: loading .envrc
direnv export: +FOO

$ echo ${FOO-nope}
foo

$ cd ..
direnv: unloading

Principais Recursos

  • Stdlib: conjunto de funções utilitárias disponíveis dentro do .envrc (ex.: PATH_add bin em vez de export PATH=$PWD/bin:$PATH), documentado na manpage direnv-stdlib(1).
  • Extensões próprias: é possível sobrescrever/estender a stdlib criando ~/.config/direnv/direnvrc ou arquivos em ~/.config/direnv/lib/*.sh, carregados antes do .envrc.
  • Suporte a .env: pode ler arquivos .env além do .envrc (a stdlib não fica disponível dentro do .env; usa-se dotenv no .envrc para combiná-los).
  • Mecanismo de segurança: .envrc novos ou alterados precisam ser explicitamente autorizados com direnv allow.

Casos de Uso

  • Carregar variáveis de ambiente de 12factor apps.
  • Criar ambientes de desenvolvimento isolados por projeto.
  • Carregar segredos apenas no contexto de deploy.
  • Construir soluções similares a rbenv, pyenv e phpenv, já que é agnóstico de linguagem.

Público-alvo

Desenvolvedores que trabalham com múltiplos projetos e querem variáveis de ambiente e configurações específicas por diretório, sem poluir o shell global.

Instalação Básica

  1. Instalar via gerenciador de pacotes da distribuição (a maioria já empacota o direnv).
  2. Adicionar o hook do direnv ao shell.
  3. Reiniciar o shell.

FAQ

  • O .envrc é carregado no shell atual? Não. O direnv cria um sub-processo bash para carregar stdlib, direnvrc e .envrc, e exporta apenas o diff de variáveis de ambiente para o shell original. Por isso, aliases e funções definidos no .envrc não são exportáveis.
  • Dá para sobrescrever a stdlib padrão? Sim, via ~/.config/direnv/direnvrc.

Limitações

  • Aliases e funções shell definidos dentro do .envrc não são propagados para o shell original (apenas variáveis de ambiente).
  • A funcionalidade da stdlib não está disponível em arquivos .env.

Projetos Relacionados

  • mise — direnv, make e asdf combinados em uma única ferramenta.
  • asdf — gerenciador de versões com plugin asdf-direnv para integração.
  • starship — prompt cross-shell complementar.

Referências

Visão de gráfico

Backlinks

  • Sem backlinks encontrados