Go

mise installs the official Go distributions and sets GOROOT and GOBIN for the selected version.

Quick start

Select a Go release series for the current project:

mise use go@1.27
mise exec -- go version

Use mise use -g go@1.27 for a personal default. mise upgrade go updates within the configured request.

Choosing a version

Request	Selects
go@1.27	The newest 1.27.x release
go@1.27.1	That release
go@latest	The newest release
go@1.20	Exactly 1.20, the first 1.20 release
go@prefix:1.20	The newest 1.20.x release

Go 1.20 and earlier published the first release of each series as 1.20, not 1.20.0, so go@1.20 selects that exact first release. To get the newest 1.20.x, use prefix::

mise use go@prefix:1.20

From Go 1.21 on, the first release is 1.21.0, so go@1.21 already selects the newest 1.21.x. Betas and release candidates are not listed. Run mise ls-remote go to see every version.

Version files

mise can select Go from .go-version, go.mod or go.work. Enable them for Go:

mise settings add idiomatic_version_file_enable_tools go

This changes your global config. Add --local to enable it in the project's mise.toml instead, so teammates get the same behavior. See idiomatic version files.

In go.mod and go.work, mise reads a toolchain goX.Y.Z directive as an exact version request. For example, this go.work selects Go 1.27.1 for a workspace containing the api and worker modules:

go.work

go 1.27.0

toolchain go1.27.1

use (
    ./api
    ./worker
)

The go directive only declares the minimum Go version that the module supports. mise ignores it in go.work. Reading it from go.mod is deprecated and stops in mise 2026.11.0; add a toolchain line instead, or set idiomatic_version_file_ignore_minimum_versions to ignore it now. See which fields mise reads.

Workspaces and GOWORK

When a workspace is active, mise uses its go.work instead of the go.mod files beneath it, including when you run mise from a module subdirectory. If the workspace has no supported toolchain directive, neither file supplies a version. Use toolchain goX.Y.Z with a full release version; mise does not read toolchain default, partial versions or release candidates.

The GOWORK environment variable controls which workspace mise uses:

GOWORK value	mise behavior
Unset, empty, or auto	Search the current directory and its parents for go.work, within mise's config search paths.
off	Ignore go.work and read go.mod.
Absolute path	Use only the named workspace file, if mise discovers it; ignore other go.work files and do not fall back to go.mod.

Setting GOWORK does not make mise read files outside its config search paths. If the named workspace is outside those paths or does not exist, it supplies no version; set the Go version in mise.toml for such a workspace. mise ignores a relative GOWORK path and uses its default search. Go itself rejects relative paths, so use an absolute path.

Go's own toolchain switching

Go has its own toolchain selection, controlled by GOTOOLCHAIN and the go and toolchain lines in go.mod and go.work. With Go's default GOTOOLCHAIN=auto, the go command that mise installed can download and run a newer toolchain when a module asks for one. Compare mise exec -- go version with mise exec -- go env GOTOOLCHAIN when the version you see is not the one mise selected. To make Go always run the toolchain mise selected, set GOTOOLCHAIN in [env]:

mise.toml

[env]
GOTOOLCHAIN = "local"

Binaries from go install

Unless GOBIN is already set in your shell, mise sets it to the selected Go version's bin directory, which is on PATH. A command installed with go install therefore belongs to that Go version and is gone after you switch or upgrade Go.

To keep a Go CLI across Go versions, install it as its own tool with the go: backend, for example mise use -g go:golang.org/x/tools/gopls. To use Go's default location ($GOPATH/bin, or ~/go/bin), set go.set_gobin to false and add that directory to your PATH yourself.

Environment variables

Variable	Value
GOROOT	The selected version's install directory. Turn off with go.set_goroot.
GOBIN	The selected version's bin directory, unless GOBIN is already set or go.set_gobin is false.

mise does not set GOPATH. Set it in [env] if you need a specific value.

How mise installs Go

mise lists Go versions from its versions host, or from the release tags of go.repo when use_versions_host is off. mise downloads the archive for your platform from go.download_mirror (https://dl.google.com/go by default), checks it against the .sha256 file published next to it, and runs go version. go.skip_checksum turns the checksum check off.

An installed plugin named go takes precedence over the built-in installer. If mise behaves differently from this page, check mise plugins ls and see selecting another implementation.

Tool options

Go has no Go-specific options. install_env reaches the go version check, go install for default packages, and postinstall commands. For example, a postinstall that installs a private module needs GOPRIVATE:

mise.toml

[tools]
go = {
  version = "1.27",
  install_env = { GOPRIVATE = "github.com/acme/*" },
  postinstall = "go install github.com/acme/tool@latest",
}

Other generic options are described in tool options.

Default packages file deprecated

mise installs the packages listed in ~/.default-go-packages (go.default_packages_file), one per line, with go install into each new Go version. mise warns about this file from 2026.11.0 and stops reading it in 2027.11.0. Install Go CLIs with the go: backend instead, for example "go:github.com/jesseduffield/lazygit" = "latest", or use a postinstall command for packages every Go version needs.

Settings

Set these under [settings] in a config file, with mise settings set, or with a setting's environment variable where it has one. See which value wins when a setting is set in more than one place.

go.default_packages_filedeprecated

File listing Go packages to install with every Go version.

• Type: path
• Default: "~/.default-go-packages"
• Environment variable: MISE_GO_DEFAULT_PACKAGES_FILE
• Deprecated: Default go package files are deprecated. Use tool-level postinstall hooks for packages that should be installed into every go version, or use the go: backend for CLI tools.

go.download_mirror

Base URL that mise downloads Go archives and their checksums from.

• Type: string
• Default: "https://dl.google.com/go"
• Environment variable: MISE_GO_DOWNLOAD_MIRROR

go.repo

Git repository mise lists Go versions from.

• Type: URL
• Default: "https://github.com/golang/go"
• Environment variable: MISE_GO_REPO

mise reads the repository's go* tags to find Go versions when it does not get them from the versions host; set use_versions_host = false to always list from this repository. Downloads come from go.download_mirror.

go.set_gobin

Set GOBIN so go install puts binaries in the active Go version's directory.

• Type: boolean
• Default: unset
• Environment variable: MISE_GO_SET_GOBIN

When unset, mise sets GOBIN to the active Go version's bin directory unless GOBIN is already set in your environment. true always sets it, replacing your GOBIN. false never sets it, so go install uses your own GOBIN or Go's default, ${GOPATH:-$HOME/go}/bin.

go.set_gopathdeprecated

Set GOPATH to the packages directory inside the active Go install.

• Type: boolean
• Default: false
• Environment variable: MISE_GO_SET_GOPATH
• Deprecated: Set GOPATH in [env] instead. When true, this setting still sets GOPATH to the Go install's packages directory.

go.set_goroot

Set GOROOT to the active Go version's install directory.

• Type: boolean
• Default: true
• Environment variable: MISE_GO_SET_GOROOT

go.skip_checksum

Skip SHA-256 verification of Go downloads.

• Type: boolean
• Default: false
• Environment variable: MISE_GO_SKIP_CHECKSUM