direnv
direnv
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.
Direnv only supports modifying environment variables, so your init_hook
functionality will be restricted. In particular, aliases, functions, and command completions will not work. If you use these, stick with the manual devbox shell
.
Prerequisites
- 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 generate direnv
and enables it by running direnv allow
in the background:
➜ devbox generate direnv
Success: generated .envrc file
Success: ran `direnv allow`
direnv: loading ~/src/devbox/docs/.envrc
direnv: using devbox
This will generate a .envrc
file in your project directory that contains devbox.json
. Run direnv allow
to activate your shell upon directory navigation. Run direnv revoke
to stop. Changes to devbox.json
automatically trigger direnv to reset the environment.
Existing Project
For an existing project, you can add a .envrc
file by running devbox generate direnv
:
➜ devbox generate direnv
Success: generated .envrc file
Success: ran `direnv allow`
direnv: loading ~/src/devbox/docs/.envrc
direnv: using devbox
Adding Custom Env Variables or Env Files to your Direnv Config
In some cases, you may want to override certain environment variables in your Devbox config when running it locally. You can add custom environment variables from the command line or from a file using the --env
and --env-file
flags.
If you would like to add custom environment variables to your direnv config, you can do so by passing the --env
flag to devbox generate direnv
. This flag takes a comma-separated list of key-value pairs, where the key is the name of the environment variable and the value is the value of the environment variable. For example, if you wanted to add a MY_CUSTOM_ENV_VAR
environment variable with a value of my-custom-value
, you would run the following command:
devbox generate direnv --env MY_CUSTOM_ENV_VAR=my-value
The resulting .envrc will have the following:
# Automatically sets up your devbox environment whenever you cd into this
# directory via our direnv integration:
eval "$(devbox generate direnv --print-envrc --env MY_CUSTOM_ENV_VAR=my-value)"
# check out https://www.jetpack.io/devbox/docs/ide_configuration/direnv/
# for more details
You can also tell direnv to read environment variables from a custom .env
file by passing the --env-file
flag to devbox generate direnv
. This flag takes a path to a file containing environment variables to set in the devbox environment. If the file does not exist, then this parameter is ignored. For example, if you wanted to add a .env.devbox
file located in your project root, you would run the following command:
devbox generate direnv --env-file .env.devbox
The resulting .envrc will have the following:
# Automatically sets up your devbox environment whenever you cd into this
# directory via our direnv integration:
eval "$(devbox generate direnv --print-envrc --env-file .env.devbox)"
# check out https://www.jetpack.io/devbox/docs/ide_configuration/direnv/
# for more details
Note that if Devbox cannot find the env file provided to the flag, it will ignore the flag and load your Devbox shell environment as normal
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.
[whitelist]
prefix = [ "/absolute/path/to/project" ]
VSCode setup with direnv
To seamlessly integrate VSCode with a direnv environment, follow these steps:
- Open a terminal window and activate direnv with
direnv allow
. - Launch VSCode from the same terminal window using the command
code .
This ensures that VSCode inherits the direnv environment.
Alternatively, you can use the direnv VSCode extension if your VSCode workspace has a .envrc file.
If this guide is missing something, feel free to contribute by opening a pull request in Github.