direnv

Grant direnv permission to load the .envrc present in the current directory

$ direnv allow [.]

$ direnv deny [.]

$ direnv edit [.]

$ direnv reload

$ direnv status

direnv <command> [<arguments>...]

allow [<path>]
    Allows the .envrc file in the current or specified directory to be loaded. This is a security measure to prevent untrusted code execution.

deny [<path>]
    Denies the .envrc file in the current or specified directory, preventing it from being loaded.

edit [<path>]
    Opens the .envrc file for editing in the current or specified directory using your default editor.

hook <shell_name>
    Prints the shell hook needed to integrate direnv into your shell. This output should be evaluated in your shell's startup file (e.g., eval "$(direnv hook bash)").

reload
    Forces direnv to reload the environment variables from the current directory's .envrc file.

exec <dir> [<command>...]
    Executes a command in the environment defined by the .envrc file in the specified directory, without changing your current shell's directory.

status
    Displays the current status of direnv, including the loaded .envrc file and modified variables.

version
    Prints the installed direnv version.

stdlib
    Prints the contents of direnv's standard library, which contains many useful helper functions for .envrc files (e.g., layout python, use node).

direnv is a powerful shell extension that automatically loads and unloads environment variables when you change directories. Instead of manually sourcing scripts or setting variables for each project, direnv allows you to define project-specific environment settings in a file named .envrc within your project's root directory.

When you navigate into a directory containing an .envrc file, direnv executes its contents, making the defined variables available to your current shell session. Upon leaving that directory, it automatically unloads them, keeping your global environment clean and preventing conflicts. This is particularly useful for managing different versions of programming languages (e.g., Node.js, Python), setting API keys, database configurations, or any other project-specific settings.

For security, direnv requires explicit permission to load an .envrc file using direnv allow, preventing arbitrary code execution. Its integration with popular shells like Bash, Zsh, and Fish is seamless, typically involving a single line added to your shell's startup file. This tool significantly enhances developer workflow efficiency and maintains a clean, context-aware shell environment.

Shell Hook Requirement: direnv relies on a shell hook to function correctly. This hook must be sourced in your shell's startup file (e.g., .bashrc, .zshrc, config.fish). Without it, direnv will not automatically load/unload environments.

Security Risk (.envrc files): Because .envrc files are arbitrary shell scripts, they can execute any command. Always review .envrc files from untrusted sources before running direnv allow. The allow/deny mechanism is crucial for security.

Performance Impact: While generally minimal, in environments with very complex .envrc files or extremely frequent directory changes, there might be a slight performance overhead during prompt rendering or directory transitions.

The .envrc file is the core configuration file for direnv. It is a plain text file containing shell commands that modify the environment. When direnv processes this file, it executes the commands within it. Common commands include export VAR=value, PATH_add /path/to/bin, or using direnv's standard library functions like layout python or use node.

direnv comes with a rich set of built-in helper functions, collectively known as the stdlib. These functions simplify common tasks within .envrc files. Examples include layout python (to automatically set up Python virtual environments), use node (for Node.js version management), path_add (to prepend a path to the PATH variable), and many more. Using the stdlib makes .envrc files more concise and robust.

direnv was created by Laurent Pluchet around 2011-2012. The motivation behind its development was to simplify the management of project-specific environment variables, addressing the common pain point of manually sourcing activation scripts (e.g., for Python virtual environments) or setting numerous `PATH` and other variables for different projects. Its elegant approach of automatic environment switching upon directory entry and exit quickly gained traction, especially as microservices and polyglot development became more prevalent, requiring developers to seamlessly switch between different project contexts and their unique environmental needs.

env(1), source(1), bash(1), zsh(1), fish(1)