asdf install: Usage, Options & Common CI Errors

asdf install installs runtime versions for many languages from one .tool-versions file.

asdf is a single version manager for many runtimes (Node, Python, Ruby, Go, and more) driven by .tool-versions. The CI gotchas are forgetting to add the plugin and the shim/PATH setup.

What it does

asdf install installs versions defined in .tool-versions across all configured plugins (or one tool/version explicitly). Each language is a plugin you add first (asdf plugin add nodejs). asdf uses shims under ~/.asdf/shims that must be on PATH, sourced via the asdf shim setup.

Common usage

. "$HOME/.asdf/asdf.sh"                          # source asdf (classic install)
asdf plugin add nodejs
asdf plugin add python
asdf install                                     # install everything in .tool-versions
asdf install nodejs 20.15.1
asdf local nodejs 20.15.1

Common errors in CI

"No preset version installed for command node ... Please install a version by running ... or add one to your .tool-versions" means the version is not installed or no .tool-versions entry exists. "Unknown command: \"asdf install nodejs\"" or "No such plugin: nodejs" means you skipped asdf plugin add nodejs. If a tool runs the system version, the asdf shims are not on PATH - source ~/.asdf/asdf.sh. Each plugin may need its own build deps (e.g. the python plugin uses pyenv's build requirements).

Options

Related guides