{"id":13929623,"url":"https://github.com/asdf-community/asdf-direnv","last_synced_at":"2026-03-11T12:49:06.667Z","repository":{"id":38148039,"uuid":"217886739","full_name":"asdf-community/asdf-direnv","owner":"asdf-community","description":"direnv plugin for the asdf version manager","archived":false,"fork":false,"pushed_at":"2024-09-13T23:42:50.000Z","size":268,"stargazers_count":542,"open_issues_count":5,"forks_count":38,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-09-14T13:51:03.577Z","etag":null,"topics":["asdf","asdf-plugin"],"latest_commit_sha":null,"homepage":"https://github.com/asdf-vm/asdf","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/asdf-community.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["smorimoto"]}},"created_at":"2019-10-27T16:55:11.000Z","updated_at":"2024-09-13T23:42:53.000Z","dependencies_parsed_at":"2024-06-20T16:34:01.811Z","dependency_job_id":"0dff42fd-94d5-46f4-afca-b55b7ad4ef14","html_url":"https://github.com/asdf-community/asdf-direnv","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asdf-community%2Fasdf-direnv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asdf-community%2Fasdf-direnv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asdf-community%2Fasdf-direnv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/asdf-community%2Fasdf-direnv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/asdf-community","download_url":"https://codeload.github.com/asdf-community/asdf-direnv/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226597769,"owners_count":17657208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asdf","asdf-plugin"],"created_at":"2024-08-07T18:02:27.068Z","updated_at":"2025-12-15T03:20:44.364Z","avatar_url":"https://github.com/asdf-community.png","language":"Shell","funding_links":["https://github.com/sponsors/smorimoto"],"categories":["others","Shell"],"sub_categories":[],"readme":"# asdf-direnv\n\n\u003e [!CAUTION]\n\u003e This project is archived.\n\u003e The asdf ecosystem has evolved since this project was created, and there are\n\u003e better alternatives.\n\u003e - If all you care about is speed, use the `go` rewrite of `asdf`\n\u003e   ([0.16+](https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md#0160-2025-01-30)).\n\u003e - If you want to avoid shims for non-speed reasons (such as confusing `which`\n\u003e   output), [mise](https://mise.jdx.dev) is an alternative \"front end\" to the\n\u003e   asdf plugin ecosystem, and it supports [PATH\n\u003e   activation](https://mise.jdx.dev/dev-tools/shims.html#path-activation).\n\n[direnv](https://direnv.net) plugin for asdf version manager\n\n## Build History\n\n[![Build history](https://buildstats.info/github/chart/asdf-community/asdf-direnv?branch=master)](https://github.com/asdf-community/asdf-direnv/actions)\n\n## Motivation (or shims de-motivation)\n\nasdf version resolution [*is slow*](https://github.com/asdf-community/asdf-direnv/issues/80#issuecomment-1079485165) which makes every command execution pay that penalty. `asdf reshim` is needed for finding new executables, and some tools are not happy with their executables being masked by shims.\n\n\u003cdetails\u003e\n\n\n[asdf](https://asdf-vm.com) is a great tool for managing multiple versions of\ncommand-line tools. 99% of the time these managed tools work just as expected.\n\nShims are just tiny wrappers created by asdf that just forward execution to the\n_real_ versioned executables installed by asdf. This way, asdf has a single\nshims directory added to your PATH and has no need of mangling the PATH for\nevery installed version.\n\nWhen you run an asdf-managed command, like `node`, it will actually execute an\nasdf-shim, which will determine the `node` version to activate according to your\n`.tool-versions` file.\n\nA downside of this is that every single time you run `node` asdf will have to\ndetermine again which version to use. Even if you haven't changed your\n`.tool-versions` file to upgrade the node version to use. And this happens for\nevery shim execution, which could lead to some users experiencing certain\n_slowness_ while asdf is looking up versions, since it has to traverse\ndirectories looking up for a .tool-versions file and probably also legacy\nversion files.\n\nAnother inconvenience is that commands installed by these tools can have some\nproblems by the way asdf shims work. For example, if a command tries to find\nitself by name in PATH (e.g. using `which my-command`) it will find the asdf\nshim executable and not the _actual_ executable delegated-to by asdf. This might\ncause problems if the command tries to use this location as an installation root\nto find auxiliary files, since shims will mask the real executable.\n\nAlso, people frequently ask why is reshim needed. Suppose you used asdf to\ninstall a package manager like `npm`, `hex`, `gem`, `cargo`, etc. Any new\nbinaries installed by these tools won't be available on PATH unless you run\n`asdf reshim`. This is because asdf has no way of knowing what the `npm install`\ncommand does, and it's until `asdf reshim` that it will figure out new\nexecutables are available and will create shims for them accordingly.\n\nAnd finally, some packages come not only with language-specific commands, but\nwith tons of system tools that will shadow those already installed on your\nsystem. While this may be desirable while the language is in use, having it\ninstalled and not activated leaves dead shims all over the place.\n\n\u003c/details\u003e\n\n## Solution\n\nPerform asdf version resolution only once and defer environment loading to direnv.\n\n\u003cdetails\u003e\n\n\nAll these previously mentioned issues can be solved by using asdf along with the\n[direnv](https://direnv.net/) tool.\n\nJust like asdf is a tools manager, direnv is an environment-variables manager.\nIt can update your shell env upon directory change and clean it up when you\nleave that directory.\n\nThis `asdf-direnv` plugin lets you install `direnv` and also provides a tiny\nscript to integrate both. Allowing `direnv` to manage any variables exposed by\nasdf tools, primarily the PATH environment, but also any other variable exposed\nby your plugin (e.g. MIX_HOME exposed by the asdf-elixir plugin).\n\nThis way, running `node` will not invoke the asdf-shim but the _real_\nasdf-managed executable in PATH. Which will improve speed since version\nresolution is out of the way and made only once by `direnv` upon entering your\nproject directory. Commands trying to find themselves in PATH will find their\nexpected location. Also, no more _reshim_ needed upon `npm install`.\n\n\u003c/details\u003e\n\n## Prerequirements\n\n- Make sure you have the required dependencies installed:\n  - curl\n  - git\n\n## Usage\n\n### Setup\n\nInstall this plugin and run the setup command for all of your preferred shells `bash`/`fish`/`zsh`.\n\n```bash\nasdf plugin-add direnv\nasdf direnv setup --shell bash --version latest\n```\n\nIf you already have a `direnv` installation, you can specify `--version system`.\n\nOtherwise this plugin can install it for you. Specify either `--version latest`\nor a [direnv release](https://github.com/direnv/direnv/releases) as shown by `asdf list-all direnv`.\n\n\nThe setup will hint which files were modified, you might want to review its changes.\nAfter setup, close and open your terminal.\n\n### Configuration\n\nBy default asdf-direnv will fail if a plugin is not installed, but is possible\nto change this using the environment variable\n`ASDF_DIRENV_IGNORE_MISSING_PLUGINS=1`\n\n### Per-Project Environments\n\nOnce direnv is hooked into your system, use the  `asdf direnv local`\ncommand on your project root directory to update your environment.\n\n``` bash\nasdf direnv local [\u003ctool\u003e \u003cversion\u003e]...\n```\n\n#### Temporary environments for one-shot commands\n\nSome times you just want to execute a one-shot commmand under certain\nenvironment without creating/modifying `.envrc` and `.tool-versions` files\non your project directory. In those cases, you might want to try using\n`asdf direnv shell`.\n\n\n``` bash\n# Enter a new shell having python and node\n$ asdf direnv shell python 3.8.10 nodejs 14.18.2\n\n# Just execute a npx command under some node version.\n$ asdf direnv shell nodejs 14.18.2 -- npx create-react-app\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003ch3\u003eUpdating\u003c/h3\u003e\u003c/summary\u003e\n\nUpdating this plugin is the same as any asdf plugin:\n\n    asdf plugin update direnv\n\nUpdating the version of direnv you use depends on which installation method you've chosen:\n\n- `system`: Nothing special required here, whenever your system package manager\n  updates direnv, this plugin will use the updated version.\n\n- `latest` or `\u003cdirenv-release-version\u003e`: Re-run `asdf direnv setup --version\n  latest --shell ...` to update to the latest version of direnv. One may optionally\n  add `--no-touch-rc-file` to the command to prevent the shell rc file from being\n  modified during the update.\n\n  (NOTE: One may alternatively `export ASDF_DIRENV_NO_TOUCH_RC_FILE=1` to permanently\n  prevent modification of shell rc files during updates.)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003ch6\u003eCached environment\u003c/h6\u003e\u003c/summary\u003e\n\nTo speed up things a lot, this plugin creates direnv `envrc` files that contain\nyour tools environment. They are created automatically whenever your `.envrc` or your\n`.tool-versions` files change.\n\nCached environment files can be found under `$XDG_CACHE_HOME/asdf-direnv/env`.\nOn most systems that resolves to `~/.config/asdf-direnv/env`. It's always safe to\nremove files on this directory since they will be re-generated if missing.\n\nIf you ever need to regenerate a cached environment file, just `touch .envrc`.\n\nAlso, the `asdf direnv envrc` command will print the path to the cached environment\nfile used for your project.\n\nNow when you leave your project directory and come back to it, direnv will\nmanage the environment variables for you really fast. For example:\n\n```bash\ndirenv: loading .envrc\ndirenv: using asdf\ndirenv: Creating env file ~/.cache/asdf-direnv/env/909519368-2773408541-1591703797-361987458\ndirenv: loading ~/.cache/asdf-direnv/env/909519368-2773408541-1591703797-361987458\ndirenv: using asdf elixir 1.8.1-otp-21\ndirenv: using asdf nodejs 12.6.0\ndirenv: export +MIX_ARCHIVES +MIX_HOME +NPM_CONFIG_PREFIX ~PATH\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003ch6\u003eBenchmark\u003c/h6\u003e\u003c/summary\u003e\n\n![benchmark](https://user-images.githubusercontent.com/38746192/67657932-8483fb80-f99b-11e9-96d8-3d46d419ea62.png)\n\n#### `node --version`\n\nwith asdf-direnv:\n\n| Mean [ms] | Min [ms] | Max [ms] | Relative |\n| --------: | -------: | -------: | -------: |\n| 4.3 ± 0.4 |      3.6 |      6.0 |     1.00 |\n\nwithout asdf-direnv:\n\n|   Mean [ms] | Min [ms] | Max [ms] | Relative |\n| ----------: | -------: | -------: | -------: |\n| 189.7 ± 2.7 |    185.6 |    194.0 |     1.00 |\n\n```bash\nhyperfine 'node --version'\n```\n\n---\n\n#### `npm install -g yarn`\n\nwith asdf-direnv:\n\n|    Mean [ms] | Min [ms] | Max [ms] | Relative |\n| -----------: | -------: | -------: | -------: |\n| 683.3 ± 17.3 |    667.9 |    725.1 |     1.00 |\n\nwithout asdf-direnv:\n\n|    Mean [ms] | Min [ms] | Max [ms] | Relative |\n| -----------: | -------: | -------: | -------: |\n| 870.0 ± 12.9 |    848.4 |    894.6 |     1.00 |\n\n```bash\nhyperfine --cleanup 'npm uninstall -g yarn' 'npm install -g yarn'\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003ch3\u003ePro-Tips\u003c/h3\u003e\u003c/summary\u003e\n\n- Take a look at `direnv help true`.\n\n- Getting `$ASDF_DIR/shims` out of the PATH.\n\n  Some users might want to bypass asdf shims altogether. To do so,\n  include only `$ASDF_DIR/bin` in your PATH but exclude the shims\n  directory.\n\n  All shims are still available via `asdf exec \u003cshim\u003e`\n\n  ```bash\n  # ~/.bashrc or equivalent\n\n  # Don't source `~/.asdf/asdf.sh`\n  PATH=\"$PATH:~/.asdf/bin\"\n  ```\n\n  Note: This will break any [global defaults](https://asdf-vm.com/guide/getting-started.html#global) you have specified in\n  `~/.tool-versions`. There are various workarounds for this:\n\n   - Do all work in project directories with their own `.envrc` and `.tool-versions`\n   - Use [`asdf direnv shell`](#temporary-environments-for-one-shot-commands) for one-shot commands\n   - Create a `~/.envrc` with `use asdf` in it\n   - Use your OS's package manager to install any tools you want globally accessible\n\n  There are pros and cons to each of these approaches, it's up to you to pick\n  the approach that works best for your workstyle.\n\n- If you want to silence the console output of direnv, you can do that by\n  setting an empty environment variable: `export DIRENV_LOG_FORMAT=\"\"`.\n\n- Some times you might need to configure IDEs or other tools to find executables\n  like package managers/code linters/compilers being used on a project of yours.\n  For example, to execute `npm` outside your project directory you can do:\n\n```bash\ndirenv exec /some/project npm\n```\n\n- Remember that activation order is important.\n\n  If a local `.tool-versions` file is present, the order of listed plugins will be\n  preserved, so that toolA will be present before toolB in PATH.\n\n```bash\n# .tool-versions\ntoolA 1.0\ntoolB 2.0\n```\n\n- You can `use asdf` even if current directory has no `.tool-versions` file.\n\n  In this case the the activated versions will be the same than those returned\n  by `asdf current` command.\n\n- You can override any tool version via environment variables.\n\n  See the asdf documentation regarding versions from environment variables.\n\n```bash\n# .envrc\nexport ASDF_PLUGIN_VERSION=1.0\nuse asdf\n```\n\n- Remember `direnv` can reload the environment whenever a file changes. By\n  default this plugin will watch any `.tool-versions` file or legacy version\n  file that explicitly selects a tool.\n\nBut you can easily watch more files when needed.\n\n```bash\n# .envrc\nwatch_file \"package.json\"\n```\n\n- Using `direnv status` can be helpful to inspect current state. Also,\n  you might want to take a look to `direnv --help`.\n\n- Using a non-empty `ASDF_DIRENV_DEBUG` will enable bash-tracing with `set -x` and skip env-cache.\n\n  For example, if you are troubleshooting or trying to debug something weird on\n  your environment, use `export ASDF_DIRENV_DEBUG=true; direnv reload` and provide any\n  relevant output on an [issue](issues/new).\n\n  Also, if you are contributing a new feature or bug-fix try running\n  `env ASDF_DIRENV_DEBUG=true bats -x test` to run all tests with trace mode. If any test\n  fails you will see more output.\n\n\u003c/details\u003e\n\n## Useful links\n\nRead [direnv documentation](https://direnv.net/) for more on `.envrc`.\n\nIf you are willing to contribute, be sure to read our [CONTRIBUTING](https://github.com/asdf-community/asdf-direnv/blob/master/CONTRIBUTING.md) guide.\n\n## License\n\nLicensed under the\n[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasdf-community%2Fasdf-direnv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasdf-community%2Fasdf-direnv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasdf-community%2Fasdf-direnv/lists"}