Guide · Open source
How to use asdf: install, manage runtime versions and tips
Updated · written with AI from the project's own documentation and checked against our catalogue data
asdf is a free, MIT-licensed command-line tool for installing and switching between versions of programming languages and runtimes on a per-project basis. It is written in Go, and you add support for each language by installing a plugin. This guide explains what asdf does, how to get the code, how the plugin and config file model works, and where it fits compared with single-language tools.
asdfasdf-vm/asdf · ★ 25.6k · MIT Install options & downloads Quick start
- 1Clone the repository. Run the git clone command from the README to download asdf from GitHub.
- 2Read the getting-started guide. Open the getting-started page on asdf-vm.com to complete setup for your system.
- 3Install a language plugin. Choose the plugin for the language you need from the asdf-plugins list and install it.
- 4Install a runtime version. Install the specific version of the language you want to use with asdf.
- 5Create a .tool-versions file. Add a .tool-versions file to your project so the required versions are recorded in one place.
- 6Check your setup. Move in and out of the project directory to confirm asdf switches versions as expected.
What asdf does and who it is for
asdf is a CLI tool that manages multiple language runtime versions on a per-project basis. The README describes it as working like gvm, nvm, rbenv and pyenv, but in one tool with one set of commands.
It suits developers who work on several projects that need different language versions, and teams that want one version config file per project. It is less useful if you only use one language and one version, since a single-language version manager may be simpler. It is also not a fit if you need a graphical interface, because the README describes a CLI tool only.
- Single CLI for multiple languages
- Consistent commands across all languages
- One global config for defaults, plus a .tool-versions file per project
- Automatically switches runtime versions as you move between directories
Install asdf from the repository
The README's install instruction is to clone the repository from GitHub. Check the documentation site at asdf-vm.com for the full getting-started guide, which covers setup in more detail.
The source does not list prerequisites, so confirm any requirements on the getting-started page before you begin.
git clone https://github.com/asdf-vm/asdf.gitAdd a plugin for your language
asdf supports each language through a plugin. The README says to simply install your language's plugin. A list of available plugins is maintained in the asdf-plugins repository linked from the documentation.
If you want support for a language that has no plugin, the README links to a plugin template and a guide for creating one. The plugin system is what makes asdf extendable.
- Browse all plugins in the asdf-plugins repository
- Create your own with the asdf-plugin-template if none exists
Set versions per project with .tool-versions
Each project can have a single .tool-versions config file, which records the runtime versions that project uses. asdf switches to those versions automatically as you move into the project directory. A global config holds your defaults in one place.
If a project already has version files from other tools, asdf can read .node-version, .nvmrc and .ruby-version, which makes migration easier.
- Use one .tool-versions file per project
- Keep defaults in the single global config
- Existing .nvmrc, .node-version and .ruby-version files are supported
Get help and shell completion
The README links to the full list of commands on the documentation site. asdf also provides shell completion for Bash, Zsh, Fish and Elvish.
For bugs or feature requests, the README points to the GitHub Issues page. Questions can also be searched or asked under the asdf-vm tag on StackOverflow, where some core team members watch.
- Full command list: asdf-vm.com/manage/commands.html
- Bugs and feature requests: GitHub Issues
- Questions: FAQ on the docs site and the asdf-vm StackOverflow tag
What people use it for
- Running a Node.js project that needs a different version from your other work
- Keeping Ruby versions separate for several client projects
- Moving from nvm, rbenv or pyenv while reusing existing .nvmrc or .ruby-version files
- Managing Elixir and Erlang versions in one tool, as the title suggests
- Giving a team one shared .tool-versions file per repository
Frequently asked questions
Is asdf free?
Yes. The repository is licensed under the MIT licence, as stated in the project information. Check the LICENSE file in the repository for the full terms.
How do I install asdf?
The README's install step is to clone the repository with git clone https://github.com/asdf-vm/asdf.git. For the complete setup steps, follow the getting-started guide on asdf-vm.com.
Does asdf have any requirements?
The source does not list prerequisites. Check the getting-started guide on asdf-vm.com for what your system needs before installing.
What is the difference between asdf and nvm?
nvm manages Node.js only. The README describes asdf as similar to nvm, rbenv and pyenv but in one tool, with a single set of commands for many languages through plugins.
Can asdf read my existing version files?
Yes. The README says asdf supports .node-version, .nvmrc and .ruby-version files, which helps when migrating from other version managers.
Is there a graphical interface for asdf?
No. The README describes asdf as a CLI tool only, so you use it from the terminal.
What are alternatives to asdf?
The project's comparable tools include nvm, rbenv, pyenv and mise. A single-language tool such as nvm or pyenv may be simpler if you only use one language.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
asdf suits developers and teams who juggle several languages or projects and want one command-line tool and one per-project version file. If you only work in one language with one version, or you prefer a graphical interface, a single-language tool or another option is likely the simpler choice.
Install options & downloads