goenv

List all available goenv commands

$ goenv commands

$ goenv install [go_version]

$ goenv local [go_version]

$ goenv global [go_version]

$ goenv versions

$ goenv uninstall [go_version]

$ goenv exec go run [go_version]

goenv [-v|--version] [-h|--help] [--debug] [--verbose] command [args]
goenv command --help

-h, --help
    Show help for specified command or all commands

-v, --version
    Display goenv version

--debug
    Enable debug output

--verbose
    Enable verbose output

install
    Install specified Go version

uninstall
    Remove installed Go version

versions [--bare|--skip-aliases]
    List installed versions; current active marked with *

global [|--unset]
    Set or unset global Go version

local [|--unset]
    Set or unset local directory Go version

shell
    Temporarily activate version in current shell

rehash
    Regenerate shims for all installed versions

which
    Locate shim or Go binary for command

version-name
    Show current Go version name

version-file
    Show path to version file (.go-version)

version-origin
    Explain how current version was set

whence
    List matching shims for command

exec []
    Execute command with GOENV_VERSION exported

goenv is a lightweight shell extension for managing multiple Go programming language versions. It enables users to install, switch, and run different Go versions per project or globally without conflicting installations.

It works by inserting executable shims into your PATH, which transparently delegate to the selected Go version. This avoids modifying your shell profile extensively and supports shell-independent operation.

Key features include per-directory version overrides via .go-version files, easy installation of Go releases, and commands for listing, uninstalling, and querying versions. goenv fetches binaries from official Go downloads, supporting all platforms.

Unlike full Go installations, goenv doesn't manage GOPATH or modules; it focuses solely on the go binary and tools like gofmt. Ideal for developers working on multiple Go projects with varying version requirements. Requires adding $GOENV_ROOT/bin and $GOENV_ROOT/shims to PATH, plus init hook in shell config.

Requires shell init (eval "$(goenv init -)" in ~/.bashrc or equivalent).
Shims must precede /usr/local/bin in PATH.
Does not manage GOPATH, GOROOT, or modules.
Large versions (e.g., race detector) consume significant disk space.
Not compatible with system Go package managers like apt.

curl https://raw.githubusercontent.com/go-env/go-env/master/bin/goenv-installer | bash
Then add to shell: export PATH="$GOENV_ROOT/bin:$GOENV_ROOT/shims:${PATH}"
eval "$(goenv init -)"

goenv install 1.21.5
goenv global 1.21.5
echo '1.20.0' > .go-version # local override
goenv shell 1.22.0 # temporary

Custom scripts in $GOENV_ROOT/hooks/category/name. Categories: init, version-name, exec. Runs at key points like version change.

goenv originated as a 2015 fork of rbenv for Ruby, adapted for Go by F. Hoffmann and contributors. Gained popularity post-Go 1.5 with modules shift. Actively maintained on GitHub (go-environ/goenv), with releases aligning to Go versions up to 1.23+. Emphasizes simplicity over feature bloat seen in predecessors like GVM.

rbenv(1), pyenv(1), nvm(1), asdf(1), g(1)