Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cachix/devenv/llms.txt

Use this file to discover all available pages before exploring further.

devenv includes a built-in shell hook that automatically activates your developer environment when you cd into a project directory. Unlike direnv-based setups, no external tools are required — just add a single line to your shell config and run one trust command per project.
Auto activation was introduced in devenv v2.1. Make sure you are on a recent version before following this guide.

​
Setup

Add the hook to your shell configuration file, then open a new terminal (or source the config file) for it to take effect.
~/.bashrc
eval "$(devenv hook bash)"

​
Trusting a Project

Before a project can auto-activate, you must explicitly trust it. This is a security measure that prevents untrusted projects from modifying your shell. Navigate to the project directory and run: 
$ cd ~/myproject
$ devenv allow
devenv: allowed /home/user/myproject
The next time you cd into the directory, devenv activates automatically: 
$ cd ~/myproject
(devenv) $

​
Revoking Trust

To stop a project from auto-activating: 
$ cd ~/myproject
$ devenv revoke
devenv: revoked /home/user/myproject

​
How It Works

The hook runs on every directory change and follows these steps:
1

Locate the project root

Walks up from the current directory looking for a devenv.nix file.
2

Check the trust database

Verifies that the discovered project directory was previously allowed via devenv allow.
3

Activate the environment

If trusted, runs devenv shell in a subshell for that project.
If a project has not been trusted yet, you will see a message: 
devenv: /home/user/myproject is not allowed. Run 'devenv allow' to trust this directory.
The hook detects projects by looking for a devenv.nix file. Before version 2.2, it looked for devenv.yaml instead, so projects with only devenv.nix were not auto-detected.

​
Automatic Deactivation

When you cd out of the project directory (or any of its subdirectories), the devenv shell exits automatically and you return to your normal shell: 
(devenv) $ cd ..
$

​
Re-entry Protection

The hook will not nest environments. While inside a devenv shell, navigating into a subdirectory of the same project keeps the current shell active. Only navigating outside the project root triggers deactivation.

​
Comparison with direnv

If you’re already using direnv, you may wonder which approach to choose. Here’s a quick comparison:
Featuredevenv hookdirenv
External dependenciesNoneRequires direnv
SetupOne line in shell configdirenv install + .envrc per project
Trust granularityPer project directoryPer .envrc file
Environment applicationSpawns a subshellModifies current shell in place
Unloading on exitSubshell exits automaticallydirenv unloads variables
Use devenv hook for a simple, dependency-free setup. Use direnv if you prefer in-place environment modification without spawning a subshell.

Build docs developers (and LLMs) love

Get started for freeTalk to us