direnv

unclutter your .profile

13,861

686

13,861

377

View on GitHub

Top Related Projects

nvm

86,158

Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

rbenv

16,468

Manage your app's Ruby environment

asdf

23,996

Extendable version manager with support for Ruby, Node.js, Elixir, Erlang & more

Quick Overview

direnv is an environment switcher for the shell. It allows you to automatically load and unload environment variables depending on the current directory. This tool is particularly useful for managing project-specific environment settings, ensuring that the correct variables are set when you enter a project directory and unset when you leave.

Pros

Seamless integration with various shells (bash, zsh, fish, etc.)
Automatic loading and unloading of environment variables
Supports multiple programming languages and frameworks
Enhances security by isolating project-specific environment variables

Cons

Requires initial setup and configuration for each project
May introduce complexity for users unfamiliar with environment management
Potential security risks if not used carefully (e.g., accidentally committing sensitive information)
Limited functionality compared to more comprehensive development environment managers

Getting Started

Install direnv using your package manager or from source:

# macOS with Homebrew
brew install direnv

# Ubuntu/Debian
sudo apt-get install direnv

Add the following to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc):

eval "$(direnv hook bash)"  # Replace 'bash' with your shell (e.g., zsh, fish)

Create a .envrc file in your project directory:

echo 'export PROJECT_API_KEY=your_api_key_here' > .envrc

Allow the .envrc file:
```
direnv allow .
```

Navigate in and out of the directory to see direnv in action:

cd /path/to/your/project  # Environment variables loaded
cd ..                     # Environment variables unloaded

Competitor Comparisons

nvm

86,158

Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Pros of nvm

Specialized for Node.js version management
Allows easy switching between Node.js versions
Supports installation of specific Node.js versions

Cons of nvm

Limited to Node.js environment management
Requires manual activation and deactivation
Can be slower to load compared to direnv

Code Comparison

nvm:

nvm install 14.17.0
nvm use 14.17.0
node -v

direnv:

echo 'use node 14.17.0' > .envrc
direnv allow
node -v

Key Differences

direnv is a more general-purpose tool for managing environment variables across various projects and languages, while nvm focuses specifically on Node.js version management. direnv automatically loads and unloads environment variables based on the current directory, whereas nvm requires manual activation of Node.js versions.

direnv integrates seamlessly with shell environments and supports multiple languages and tools, making it more versatile for complex project setups. nvm, on the other hand, provides a more straightforward and specialized approach to managing Node.js versions, which can be beneficial for developers working primarily with Node.js projects.

pyenv

42,787

Simple Python version management

Pros of pyenv

Specifically designed for managing multiple Python versions
Allows easy switching between Python versions per project or globally
Supports installation of various Python implementations (CPython, PyPy, etc.)

Cons of pyenv

Limited to Python environment management only
Requires manual configuration of environment variables
More complex setup process compared to direnv

Code Comparison

pyenv:

pyenv install 3.9.0
pyenv local 3.9.0
python --version

direnv:

echo 'use python 3.9.0' > .envrc
direnv allow
python --version

Key Differences

Scope: pyenv focuses solely on Python version management, while direnv handles environment variables for any project type.
Automation: direnv automatically loads/unloads environment settings when entering/leaving directories, whereas pyenv requires manual switching.
Flexibility: direnv can manage various environment variables and settings beyond just Python versions, making it more versatile for different project needs.

Both tools serve different purposes and can be complementary in a developer's toolkit. pyenv excels at managing multiple Python versions, while direnv offers broader environment management capabilities across various project types.

rbenv

16,468

Manage your app's Ruby environment

Pros of rbenv

Specifically designed for managing Ruby versions
Provides a seamless way to switch between different Ruby versions per project
Integrates well with Ruby-specific tools and workflows

Cons of rbenv

Limited to Ruby environment management only
Requires additional plugins for managing gemsets or other language-specific features
May have a steeper learning curve for users not familiar with Ruby ecosystem

Code Comparison

rbenv:

# Install a Ruby version
rbenv install 3.0.0

# Set global Ruby version
rbenv global 3.0.0

# Set local Ruby version for a project
rbenv local 2.7.2

direnv:

# Create a .envrc file in your project directory
echo 'export RUBY_VERSION=3.0.0' > .envrc

# Load the environment
direnv allow

# Automatically switches environment when entering/leaving directory
cd /path/to/project

direnv is a more general-purpose tool for managing environment variables across different projects and languages, while rbenv is specifically tailored for Ruby version management. direnv offers greater flexibility for multi-language projects, whereas rbenv provides a more streamlined experience for Ruby-centric development workflows.

asdf

23,996

Extendable version manager with support for Ruby, Node.js, Elixir, Erlang & more

Pros of asdf

Manages multiple runtime versions for various languages and tools
Provides a unified interface for installing and switching between versions
Supports plugins for extending functionality to additional tools

Cons of asdf

Requires manual configuration for each project
May have a steeper learning curve for new users
Can be slower to load compared to direnv's lightweight approach

Code Comparison

asdf:

# .tool-versions
nodejs 14.17.0
ruby 3.0.1

direnv:

# .envrc
use node 14.17.0
use ruby 3.0.1

Key Differences

asdf focuses on version management across multiple tools, while direnv is primarily for environment variables and directory-specific settings
direnv automatically loads/unloads environment settings when entering/leaving directories, whereas asdf requires manual switching
asdf provides a centralized configuration for all projects, while direnv allows for project-specific configurations

Use Cases

asdf is ideal for developers working with multiple languages and tools across various projects
direnv is better suited for projects with complex environment setups or those requiring quick switching between different environments

Community and Ecosystem

Both projects have active communities and regular updates
asdf has a larger plugin ecosystem due to its focus on supporting multiple tools
direnv integrates well with various shells and development workflows

sdkman-cli

6,446

The SDKMAN! Command Line Interface

Pros of SDKMAN

Specialized for managing multiple versions of JDK and Java-related tools
Provides a curated list of SDKs and tools for easy installation
Offers a simple command-line interface for SDK management

Cons of SDKMAN

Limited to Java ecosystem tools and SDKs
Requires manual activation and deactivation of environments
Less flexible for managing non-Java project environments

Code Comparison

SDKMAN:

sdk install java 11.0.12-open
sdk use java 11.0.12-open

direnv:

echo 'export JAVA_HOME=/path/to/java/11' > .envrc
direnv allow

Key Differences

Scope: SDKMAN focuses on Java ecosystem, while direnv is language-agnostic
Activation: SDKMAN requires manual activation, direnv automatically loads/unloads environments
Configuration: SDKMAN uses a global configuration, direnv uses per-directory .envrc files
Flexibility: direnv can manage any environment variable, SDKMAN is limited to predefined SDKs

Use Cases

SDKMAN is ideal for Java developers managing multiple JDK versions and related tools. direnv is better suited for projects with diverse technology stacks or those requiring fine-grained environment control across different directories.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

direnv -- unclutter your .profile

direnv is an extension for your shell. It augments existing shells with a new feature that can load and unload environment variables depending on the current directory.

Use cases

Load 12factor apps environment variables
Create per-project isolated development environments
Load secrets for deployment

How it works

Before each prompt, direnv checks for the existence of a .envrc file (and optionally a .env file) in the current and parent directories. If the file exists (and is authorized), it is loaded into a bash sub-shell and all exported variables are then captured by direnv and then made available to the current shell.

It supports hooks for all the common shells like bash, zsh, tcsh and fish. This allows project-specific environment variables without cluttering the ~/.profile file.

Because direnv is compiled into a single static executable, it is fast enough to be unnoticeable on each prompt. It is also language-agnostic and can be used to build solutions similar to rbenv, pyenv and phpenv.

Getting Started

Prerequisites

Unix-like operating system (macOS, Linux, ...)
A supported shell (bash, zsh, tcsh, fish, elvish, powershell, murex, nushell)

Basic Installation

direnv is packaged in most distributions already. See the installation documentation for details.
hook direnv into your shell.

Now restart your shell.

Quick demo

To follow along in your shell once direnv is installed.

# Create a new folder for demo purposes.
$ mkdir ~/my-project
$ cd ~/my-project

# Show that the FOO environment variable is not loaded.
$ echo ${FOO-nope}
nope

# Create a new .envrc. This file is bash code that is going to be loaded by
# direnv.
$ echo export FOO=foo > .envrc
.envrc is not allowed

# The security mechanism didn't allow to load the .envrc. Since we trust it,
# let's allow its execution.
$ direnv allow .
direnv: reloading
direnv: loading .envrc
direnv export: +FOO

# Show that the FOO environment variable is loaded.
$ echo ${FOO-nope}
foo

# Exit the project
$ cd ..
direnv: unloading

# And now FOO is unset again
$ echo ${FOO-nope}
nope

The stdlib

Exporting variables by hand is a bit repetitive so direnv provides a set of utility functions that are made available in the context of the .envrc file.

As an example, the PATH_add function is used to expand and prepend a path to the $PATH environment variable. Instead of export PATH=$PWD/bin:$PATH you can write PATH_add bin. It's shorter and avoids a common mistake where $PATH=bin.

To find the documentation for all available functions check the direnv-stdlib(1) man page.

It's also possible to create your own extensions by creating a bash file at ~/.config/direnv/direnvrc or ~/.config/direnv/lib/*.sh. This file is loaded before your .envrc and thus allows you to make your own extensions to direnv.

Note that this functionality is not supported in .env files. If the coexistence of both is needed, one can use .envrc for leveraging stdlib and append dotenv at the end of it to instruct direnv to also read the .env file next.

Docs

Make sure to take a look at the wiki! It contains all sorts of useful information such as common recipes, editor integration, tips-and-tricks.

Man pages

FAQ

Based on GitHub issues interactions, here are the top things that have been confusing for users:

direnv has a standard library of functions, a collection of utilities that I found useful to have and accumulated over the years. You can find it here: https://github.com/direnv/direnv/blob/master/stdlib.sh
It's possible to override the stdlib with your own set of function by adding a bash file to ~/.config/direnv/direnvrc. This file is loaded and its content made available to any .envrc file.
direnv is not loading the .envrc into the current shell. It's creating a new bash sub-process to load the stdlib, direnvrc and .envrc, and only exports the environment diff back to the original shell. This allows direnv to record the environment changes accurately and also work with all sorts of shells. It also means that aliases and functions are not exportable right now.

Contributing

Bug reports, contributions and forks are welcome. All bugs or other forms of discussion happen on http://github.com/direnv/direnv/issues .

Or drop by on Matrix to have a chat. If you ask a question make sure to stay around as not everyone is active all day.

Testing

To run our tests, use these commands: (you may need to install homebrew)

brew bundle
make test

Complementary projects

Here is a list of projects you might want to look into if you are using direnv.

starship - A cross-shell prompt.
Projects for Nix integration - choose from one of a variety of projects offering improvements over Direnv's built-in use_nix implementation.

Related projects

Here is a list of other projects found in the same design space. Feel free to submit new ones.

Environment Modules - one of the oldest (in a good way) environment-loading systems
autoenv - older, popular, and lightweight.
zsh-autoenv - a feature-rich mixture of autoenv and smartcd: enter/leave events, nesting, stashing (Zsh-only).
asdf - a pure bash solution that has a plugin system. The asdf-direnv plugin allows using asdf managed tools with direnv.
ondir - OnDir is a small program to automate tasks specific to certain directories
shadowenv - uses an s-expression format to define environment changes that should be executed
quickenv - an alternative loader for .envrc files that does not hook into your shell and favors speed over convenience.
mise - direnv, make and asdf all in one tool.

Commercial support

Looking for help or customization?

Get in touch with Numtide to get a quote. We make it easy for companies to work with Open Source projects: https://numtide.com/contact

COPYRIGHT

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot