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. Examples: `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