Joshua's Docs - asdf Version Manager - Cheatsheet and Notes

asdf Commands

There is a full command list for ASDF

🚨 asdf does not automatically sync versions as far as listing what is available. For example, you should run asdf plugin update --all or asdf plugin update nodejs before trusting that asdf list all nodejs is giving up-to-date results

Helpful commands:

Command Explanation
asdf list all {PLUGIN} {SEMVER} Lists all available versions of a plugin, for a given /minor/patch version release.

asdf list all nodejs 16
asdf list all nodejs 16.11
asdf list all nodejs 16 | tail -n 1
asdf list all {PLUGIN} Lists all available versions of a plugin
asdf list {PLUGIN} Lists all locally (already installed) versions of a plugin
asdf local {PLUGIN} {VERSION} Set local version
asdf install {PLUGIN} {VERSION} Install version
asdf plugin add {PLUGIN} {SRC} Install a plugin
asdf plugin list List installed plugins
asdf current {PLUGIN} Show current version of plugin

asdf - Handling Global Versions

At first glance, it might not be clear how to use asdf outside of a specific project, or what the default would be if a project does not specify versions to use.

The trick is to install a specific version first, then set the global version setting. Something like this:

asdf install nodejs latest
asdf global nodejs latest

If the global version doesn't seem to switch after running these commands, try reloading your shell.

asdf - Global Packages

When you use the -g or --global with npm install, packages get installed into a shared global directory, as opposed to the current working directory's node_modules. With asdf it can be a bit confusing on where these live, as doing where {LIBRARY_NAME} will just return {USER_PATH}/.asdf/shims/{LIBRARY_NAME}, but that isn't really the true path.

To get the path of a global package's executable, use asdf which LIBRARY_NAME.

However, this is still not the true path; it is usually a symlink the CLI entrypoint. To get the real path, you can use readlink -f $(asdf which LIBRARY_NAME) (or greadlink on macOS).

asdf - Configuring per Project / Directory

For automatic configuration per directory it is recommended to use a .tool-versions file (which can control multiple tools at the same time) as opposed to tool-specific config files (such as .node-version).

📄 Docs: Configuration

For manual configuration from the CLI, use asdf local {name} {version} to set the local version.

.tool-versions format is {name} {version} per line, like:

golang 1.19
nodejs 20.4.0

# comments are supported

asfd - Troubleshooting

  • When in doubt, restart things (shell, tmux session, etc.)
  • If asdf is only not working in tmux (e.g., on the start of a new session you get an error), try restarting the ENTIRE tmux server, not just the session
    • tmux kill-server and tmux start (or tmux start-sever)

.../.asdf/shims/.../Cellar/asdf/... no such file or directory...*

Try re-shim-ing

rm ~/.asdf/shims/*
asdf reshim
Markdown Source Last Updated:
Sun Aug 06 2023 06:26:50 GMT+0000 (Coordinated Universal Time)
Markdown Source Created:
Wed Jan 04 2023 17:33:31 GMT+0000 (Coordinated Universal Time)
© 2023 Joshua Tzucker, Built with Gatsby