DIRENV.TOML(1)

📦
version 2.38.2 · 5 versions
, in alpine 3.24, arch rolling, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 NAME

direnv.toml — bestie, it's literally the direnv configuration file 👑

✨ DESCRIPTION

Okay so listen: this is a config file, written in TOML format, and it's where you tell direnv all your little preferences. The TOML spec lives over at https://github.com/toml-lang/toml if you wanna go read it (slay).

direnv reads this file from $XDG_CONFIG_HOME/direnv/direnv.toml — which for basically everyone is ~/.config/direnv/direnv.toml.

🚨 Old-school girlies, this one's for you: on versions v2.21.0 and below, use config.toml instead of direnv.toml. Not direnv.toml. Periodt.

🌸 FORMAT

Wanna know the syntax? The TOML GitHub Repository at https://github.com/toml-lang/toml has all the deets on how the config file is written. Go be nosy, it's fine 🦋

🎀 CONFIG

So the config is split into sections, and each section gets its own top-level tables (yeah, the table thing — https://github.com/toml-lang/toml#table), with key/value pairs living inside each section.

Example, because we love a visual:

[section]
key = "value"

These are the sections that are supported, no cap:

🌐 [global]

  • bash_path — lets you hard-code exactly where bash is. Lowkey useful when you wanna stop direnv from absolutely falling apart the moment PATH gets mutated 💀
  • disable_stdin — set it to true and stdin gets disabled (redirected to /dev/null) while the .envrc is being evaluated.
  • load_dotenv — requires direnv >= 2.31.0. Set it to true and direnv will also look for and load .env files on top of the .envrc files. And if both a .envrc and a .env exist? The .envrc is always chosen first, no debate ✨
  • strict_env — set it to true and the .envrc gets loaded with set -euo pipefail. Also bestie, heads up: this option is gonna be the default in the future. Future-proofing, we love to see it.
  • warn_timeout — how long to wait before direnv warns you that your command is taking way too long to execute. Defaults to "5s". A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". This feature is disabled if the duration is lower or equal to zero. And it will be overwritten if the environment variable DIRENV_WARN_TIMEOUT is set to any of the above values. So like, the env var wins, always.
  • hide_env_diff — set to true to hide the diff of the environment variables when loading the .envrc. Defaults to false.
  • log_format — sets the log format for direnv outputs. Set it to "-" to disable normal logging entirely. Requires direnv >= 2.36.0.
  • log_filter — a Regexp that you can use to filter out some of the logs. Requires direnv >= 2.36.0.

🛡️ [whitelist]

Bestie. Sit down. 🫶 Specifying whitelist directives marks specific directory hierarchies or specific directories as "trusted" — meaning direnv will evaluate any matching .envrc files regardless of whether they've actually been allowed.

💀 This feature should be used with great care, because anyone with the ability to write files to that directory (yes, including collaborators on VCS repositories) will be able to execute arbitrary code on your computer. Like. Anyone. Any code. Be so serious about this one.

There are two types of whitelist directives supported:

  • prefix — accepts an array of strings. If any of the strings in this list are a prefix of an .envrc file's absolute path, that file will be implicitly allowed, regardless of contents or past usage of direnv allow or direnv deny.

Example:

[whitelist]
prefix = [ "/home/user/code/project-a", "~/code/project-b" ]

In this example, the following .envrc files will be implicitly allowed:

  • /home/user/code/project-a/.envrc
  • /home/user/code/project-a/subdir/.envrc
  • ~/code/project-b/.envrc
  • ~/code/project-b/subdir/.envrc
  • and so on

In this example, the following .envrc files will not be implicitly allowed (although they can be explicitly allowed by running direnv allow):

  • /home/user/project-c/.envrc
  • /opt/random/.envrc
  • exact — accepts an array of strings. Each string can be a directory name or the full path to an .envrc file. If a directory name is passed, it will be treated as if it had been passed as itself with /.envrc appended. After resolving the filename, each string will be checked for being an exact match with an .envrc file's absolute path. If they match exactly, that .envrc file will be implicitly allowed, regardless of contents or past usage of direnv allow or direnv deny.

Example:

[whitelist]
exact = [ "/home/user/project-a/.envrc", "~/project-b/subdir-a" ]

In this example, the following .envrc files will be implicitly allowed, and no others:

  • /home/user/code/project-a/.envrc
  • ~/project-b/subdir-a

In this example, the following .envrc files will not be implicitly allowed (although they can be explicitly allowed by running direnv allow):

  • /home/user/code/project-b/subproject-c/.envrc
  • ~/code/.envrc

MIT licence - Copyright (C) 2019 @zimbatm and contributors

🔗 SEE ALSO

direnv(1), direnv-stdlib(1)

And that's the whole page, bestie 💜 this was direnv.toml, from the direnv manual set, dated 2019. Go forth and configure responsibly — especially that whitelist section, I'm watching you 👀✨

📦 where this page comes from