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 <command> [<args>]

install <version>
    Installs a specific Go version. For example, goenv install 1.18.1.

uninstall <version>
    Removes a previously installed Go version from your system.

global [<version>]
    Sets the global Go version. If no version is specified, it shows the current global version. This version is used if no local or shell version is defined.

local [<version>]
    Sets the project-specific Go version. This creates a .go-version file in the current directory, which takes precedence over the global version.

shell [<version>]
    Sets the Go version for the current shell session. This takes precedence over both local and global versions, and is typically temporary.

versions
    Lists all installed Go versions and indicates the currently active one with an asterisk.

version
    Displays the currently active Go version determined by goenv.

rehash
    Rebuilds the shim binaries for all installed Go versions. This is necessary after installing new Go tools or commands via go install from a specific Go version.

exec <command> [<args>]
    Executes a Go command using the currently active Go version, bypassing shims. Useful for scripting.

which <command>
    Displays the full path to the executable that goenv would use for the given command, based on the current version.

root
    Displays the directory where goenv stores its installed Go versions and shims (typically ~/.goenv).

goenv is a command-line utility designed to simplify the process of managing multiple Go programming language versions on a single machine. It allows developers to easily switch between different Go installations, ensuring that the correct version is used for specific projects or globally.

Unlike other version managers that might modify system paths directly, goenv operates using a non-invasive shim mechanism. When you invoke a Go command (like go build or go run), goenv intercepts the call and directs it to the appropriate Go executable based on the version configured for your current directory, your shell session, or globally. This functionality is achieved by inserting goenv's shim directory at the front of your $PATH environment variable.

This tool is particularly useful for teams working on projects that require different Go versions, or for individual developers who need to test their code against various Go releases. It helps in maintaining a clean development environment, avoiding conflicts that can arise from conflicting Go installations.

For goenv to function correctly, it requires proper shell integration. This usually involves adding eval "$(goenv init -)" to your shell's profile file (e.g., ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish). Without this, the necessary environment variables and shims will not be loaded. Additionally, goenv relies on your system having the necessary build tools (like a C compiler, git, etc.) to compile Go from source, which is how goenv install often operates. It does not manage Go modules directly, but manages the Go toolchain that handles modules.

After installing goenv (e.g., via git clone or a package manager), you must initialize it in your shell. Add the following line to your shell's configuration file (~/.bashrc, ~/.zshrc, etc.):

echo 'eval "$(goenv init -)"' >> ~/.bashrc

Then, restart your shell or run source ~/.bashrc (or your respective config file) for the changes to take effect. This command sets up the necessary $PATH modifications and shell functions that enable goenv's version switching capabilities.

goenv uses shims to intercept Go commands. When goenv is initialized, its shim directory (e.g., ~/.goenv/shims) is prepended to your $PATH. This directory contains lightweight executable files (shims) for every Go command (like go, gofmt, go install). When you run a command like go build, your shell finds the goenv shim first. The shim then determines which Go version to use based on the global, local (via .go-version file), or shell configuration, and executes the actual Go command from that version's installation directory, transparently redirecting the command call.

goenv emerged as part of a family of version management tools, heavily inspired by the success of rbenv for Ruby. The motivation behind its creation was to provide a similar, lightweight, and unintrusive method for managing multiple versions of the Go programming language. Its design principles emphasize simplicity and reliance on core shell features like $PATH manipulation and command shims, rather than modifying system-wide configurations or requiring elevated privileges. This approach allows developers to maintain isolated and reproducible Go development environments effortlessly, a common need in modern software development.

go(1), rbenv(1), pyenv(1), nvm(1), chsh(1), PATH(7)