Skip to main content



direnv is an open source environment management tool that allows setting unique environment variables per directory in your file system. This guide covers how to configure direnv to seamlessly work with a devbox project.


Devbox 0.5.0 makes changes to how the environment is sourced in order to ensure better compatibility with the user's host shell. This may raise some errors if you generated your .envrc file with an older version of devbox.

If you see any errors when activating your .envrc file, you will need to run devbox generate direnv --force, and then re-run devbox shell to apply the latest changes. Be sure to back up your old .envrc file before running this command.


  • Install direnv and hook it to your shell. Follow this guide if you haven't done it.

Setting up Devbox Shell and direnv

New Project

If you have direnv installed, Devbox will generate an .envrc file when you run devbox init and enables it by running direnv allow in the background:

➜  devbox init
direnv: loading ~/src/devbox/docs/.envrc
direnv: using devbox

This will generate a .envrc file in your root directory along with your devbox.json, you can run direnv allow so that your shell will activate whenever you navigate to the directory or direnv revoke to stop.

Existing Project

For an existing project, you can add a .envrc file by running devbox generate direnv:

➜  devbox generate direnv
direnv: loading ~/src/devbox/docs/.envrc
direnv: using devbox

Global settings for direnv

Note that every time changes are made to devbox.json via devbox add ..., devbox rm ... or directly editing the file, requires direnv allow to run so that direnv can setup the new changes.

Alternatively, a project directory can be whitelisted so that changes will be automatically picked up by direnv. This is done by adding following snippet to direnv config file typically at ~/.config/direnv/direnv.toml. You can create the file and directory if it doesn't exist.

prefix = [ "/absolute/path/to/project" ]

If this guide is missing something, feel free to contribute by opening a pull request in Github.