asdf-golang Plugin

The plugin uses different logic for selecting Go versions depending on the configuration file present:

• .tool-versions or .go-version: The exact version specified in the file is selected.
• go.mod: The highest compatible version currently installed is selected. This follows the Go modules reference: the highest minor version with a matching major version (e.g., a go 1.14 directive selects the highest installed 1.x.x version where x is at least 14).

Note: You can explicitly enable or disable go.mod and go.work version selection by setting the ASDF_GOLANG_MOD_VERSION_ENABLED environment variable. It defaults to true.

To ensure Golang environment variables are correctly set, you must source the appropriate set-env script in your shell configuration. This is necessary if you use a custom ASDF_DATA_DIR.

Add the corresponding line to your shell's configuration file:

# Zsh (.zshrc)
. ${ASDF_DATA_DIR:-$HOME/.asdf}/plugins/golang/set-env.zsh

# Bash (.bashrc)
. ${ASDF_DATA_DIR:-$HOME/.asdf}/plugins/golang/set-env.bash

# Fish (config.fish)
source (echo $ASDF_DATA_DIR | if test -z $it; echo $HOME/.asdf; else echo $it; end)/plugins/golang/set-env.fish

# Nushell (env.nu)
source (if ($env.ASDF_DATA_DIR | empty?) { echo $nu.env.HOME/.asdf } { echo $env.ASDF_DATA_DIR })/plugins/golang/set-env.nu

If you need to install an older version of Go that does not have a native build for your current architecture (e.g., installing an older Go version on an Apple M1/ARM chip), use the ASDF_GOLANG_OVERWRITE_ARCH environment variable to force a specific architecture (like amd64).

ASDF_GOLANG_OVERWRITE_ARCH=amd64 asdf install golang 1.15.8

To install the asdf-golang plugin for the asdf version manager, run the following command:

Requirements

MacOS

• GNU Core Utils (brew install coreutils)

Linux (Debian)

• GNU Core Utils (apt install coreutils)
• curl (apt install curl)

asdf plugin add golang https://github.com/asdf-community/asdf-golang.git

You can configure asdf-golang to automatically install a set of packages using go get -u $PACKAGE immediately after installing a new Go version.

1. Create a file at $HOME/.default-golang-pkgs.
2. List one package per line (comments are allowed).

To use a different file location, set the ASDF_GOLANG_DEFAULT_PACKAGES_FILE environment variable.

// allows comments
github.com/Dreamacro/clash
github.com/jesseduffield/lazygit

The asdf-golang plugin provides an environment variable to bypass the authenticity check of the downloaded Go archive. This is useful in environments where checksum tools are unavailable or when you have already verified the download through other means.

Set ASDF_GOLANG_SKIP_CHECKSUM to any value (e.g., 1 or true) to skip the check_shasum step.

When ASDF_INSTALL_VERSION is not set to system, the exec-env script configures the Go environment by setting GOROOT, GOPATH, and GOBIN relative to the ASDF_INSTALL_PATH. This ensures that Go tools and packages are isolated within the asdf-managed installation directory.

If these variables are not already set in your environment, exec-env will export them as follows:

• GOROOT: $ASDF_INSTALL_PATH/go
• GOPATH: $ASDF_INSTALL_PATH/packages
• GOBIN: $ASDF_INSTALL_PATH/bin

if [ "${ASDF_INSTALL_VERSION}" != 'system' ]; then
  if [[ "unset" == "${GOROOT:-unset}" ]]; then
    export GOROOT=$ASDF_INSTALL_PATH/go
  fi

if [[ "unset" == "${GOPATH:-unset}" ]]; then
    export GOPATH=$ASDF_INSTALL_PATH/packages
  fi

if [[ "unset" == "${GOBIN:-unset}" ]]; then
    export GOBIN=$ASDF_INSTALL_PATH/bin
  fi
fi

The bin/list-all script retrieves a list of all available Go version tags from the official golang/go GitHub repository. It filters the tags to provide a clean, sorted list of version strings that can be used with asdf install golang <version>.

# Run the script to see available versions
./bin/list-all