asdf is a versatile version manager designed to simplify the management of multiple runtime versions, such as programming languages, tools, and frameworks, within a single development environment. With asdf, users can easily install, manage, and switch between different versions of various software packages, ensuring compatibility and flexibility across projects. Whether you’re a developer, system administrator, or anyone who needs to juggle multiple versions of tools, asdf provides a seamless solution, enhancing productivity and eliminating version-related headaches.

Quick Guide: Setting a Specific Runtime Version for a Project with asdf

Navigate to your project’s directory:

cd ~/Project/

If your project already has a .tool-versions file, you can directly install the specified versions with:

asdf install

If your project does not have a .tool-versions file, you’ll need to create one. Here’s how to set Go version 1.17.5 as an example:

(Here go v.1.21.6 as example)

asdf install golang 1.21.6
asdf local golang 1.21.6
source ~/.zshrc 

You can then check the Go version to confirm the correct version is being used:

go version

This should output something like go version go1.17.5 darwin/amd64, confirming that Go version 1.17.5 is set for this project.

From begining

  1. Install asdf

To install asdf, you can use the Homebrew package manager on a Mac.

Run the following command to install asdf:

brew install asdf

To find the location of asdf, you can use the following command:

brew --prefix asdf

This command will return the location where asdf is installed. For example, it might show /opt/homebrew/opt/asdf/libexec/

Once you have the location, you need to add to your .zshrc file. You can do this by opening the file with vim ~/.zshrc and adding the following line:

. /opt/homebrew/opt/asdf/libexec/

After adding this line, you need to refresh your .zshrc file with the following command:

source ~/.zshrc

create local .asdf config file

'legacy_version_file = yes' > ~/.asdfrc
  1. Confirm local asdf info

Check asdf version


Confirm plugin and version

asdf current

Filter and list all support plugin

asdf plugin list all golang

List all support language version

asdf list-all golang

Show current golang version

asdf current golang 

If no current golang, can install by following command:

asdf plugin add golang

Install the latest golang version

asdf install golang latest
  1. Setting global version

To set a global version in asdf, you can use the asdf global command followed by the name of the tool and the version number. Here’s an example:

asdf global <tool_name> <version_number>

Replace <tool_name> with the name of the tool you want to set the global version for, and <version_number> with the version number you want to set as the global version.

For example, if you want to set golang version 1.21.6 as the global version, you would use:

asdf global golang 1.21.6

This command sets the specified version as the global version for the specified tool. This means that this version will be used in all directories that do not have a tool-specific version set.

  1. Setting local project version

To set a version for a specific directory in asdf, you can use the asdf local command followed by the name of the tool and the version number. Here’s an example:

asdf local <tool_name> <version_number>

For example, if you want to set golang version 1.19.4 as the global version, you would use:

asdf local golang 1.19.4 

This command creates a .tool-versions file in the current directory with the specified tool and version. This version will be used when you’re in this directory.

The .tool-versions file is a key component of asdf’s version management. When you set a local version of a tool using the asdf local command, asdf creates a .tool-versions file in the current directory. This file specifies the versions of tools that should be used in this directory. When you run a tool in this directory, asdf will use the version specified in the .tool-versions file. This allows you to have different versions of the same tool in different projects.

After setting local version, you need to refresh your .zshrc file with the following command:

source ~/.zshrc

Refreshing the .zshrc file is necessary because this file is where the shell environment is configured. When you make changes to the .zshrc file, such as adding a line to initialize asdf, these changes are not immediately applied to your current shell session. By running source ~/.zshrc, you’re telling the shell to read and execute the commands in the .zshrc file in the current shell environment. This applies any changes you made to the .zshrc file, allowing asdf to function correctly in your current shell session.


Plugin golang's list-all callback script failed with output:
remote: ========================================================================
remote: The project you were looking for could not be found or you don't have permission to view it.
remote: ========================================================================


In conclusion, this article provides a thorough and practical guide on how to use asdf for managing multiple runtime versions. It covers the installation process, setting global and local versions, and effectively managing these versions. The article also explains the importance of the .tool-versions file and the necessity of refreshing the .zshrc file when changes are made.

By following this guide, developers can easily manage different versions of tools for different projects, ensuring compatibility and reducing potential conflicts between different versions of the same tool. This makes asdf an invaluable tool for any developer’s toolkit.