Skip to content
Get packs

Guide · Open source

How to use gvm: install and switch Go versions

Updated · written with AI from the project's own documentation and checked against our catalogue data

gvm (Go Version Manager) is a shell-based command-line tool from moovweb that lets you install several versions of Go on one machine and switch between them. This guide is for developers comfortable with the terminal who need different Go versions for different projects. By the end you will know how to install gvm, install and switch Go versions, list them, and manage package sets.

gvmmoovweb/gvm · ★ 11.7k · MIT

Quick start

  1. 1Install prerequisites. Install Bison, curl, git, Mercurial, gcc and make for your operating system, as listed in the README.
  2. 2Install gvm. Run the gvm-installer script from the moovweb/gvm repository, using bash or zsh.
  3. 3Install a Go version. Run gvm install with a tag such as go1.4, then use gvm use to activate it.
  4. 4Set a default. Add --default to gvm use if you want that version to be the default.
  5. 5Check installed versions. Run gvm list to see installed versions; the current one is marked with =>.
  6. 6Create a package set. Run gvm pkgset create with a name, then gvm pkgset use to switch to that isolated Go workspace.

What you need before installing gvm

gvm is a shell tool and the README documents requirements for Mac OS X, Linux and FreeBSD. Its prerequisites are Bison, curl, git, Mercurial, gcc and make. Compiling Go from source needs gcc and make, so install them if you plan to build versions from source.

  • Mac OS X: install Xcode Command Line Tools and Mercurial (the README suggests Homebrew for Mercurial).
  • Debian/Ubuntu: the README lists curl, git, mercurial, make, binutils, bison, gcc and build-essential.
  • Redhat/CentOS: the README lists curl, git, make, bison, gcc and glibc-devel, plus Mercurial from a third-party repository.
  • FreeBSD: the README lists bash, git and mercurial.

Install gvm

First install Bison. Then run the gvm installer script. The README notes that if you use zsh, replace bash with zsh in the command.

  • Install Bison on Debian/Ubuntu.
  • Run the gvm installer.
sudo apt-get install bison bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)

Install and switch Go versions

Install a Go version with gvm install, then activate it with gvm use. The README says that once this is done Go will be in the path, and $GOROOT and $GOPATH are set automatically. Add --default to make the version the default with gvm use. Version tags can look like go1.4, 60.3, weekly.2011-11-08 or tip.

Installing Go 1.5 or later needs a working Go toolchain for bootstrapping. The README says to install Go 1.4 first, then set GOROOT_BOOTSTRAP before building newer versions. Use the -B option to install from a binary.

  • -s, --source: install Go from a specified source.
  • -n, --name: override the default name for this version.
  • -B, --binary: only install from binary.
  • --prefer-binary: try a binary install, falling back to source.
  • -b, --with-build-tools: install package build tools.
  • -pb, --with-protobuf: install Go protocol buffers.
gvm install go1.4 gvm use go1.4 --default gvm install go1.4 -B gvm use go1.4 export GOROOT_BOOTSTRAP=$GOROOT gvm install go1.7

List installed and available Go versions

Use gvm list to see installed versions; the current one is prefixed with "=>". Use gvm listall to see versions available for download. The README says gvm listall shows the latest release tags and --all also includes weekly tags.

gvm list gvm listall

Manage package sets and project directories

Package sets (pkgsets) are separate Go workspaces, which the README describes as managing GOPATHs. Create, use and delete them with gvm pkgset. Pass --local as the name to keep a repository's workspace under the local path /path/to/repo/.gvm_local. gvm can also link project directories into GOPATH and diff the files in GOROOT with gvm diff.

  • gvm diff: list added and removed files in GOROOT.
  • gvm pkgset create, use or delete [name]: manage a package set.
  • gvm pkgset [name] --local: keep the workspace under the repository's .gvm_local path.
gvm pkgset create myproject gvm pkgset use myproject

Remove gvm or reset its files

To remove gvm and all installed Go versions and packages, run gvm implode. The README says that if that does not work, you can run rm -rf ~/.gvm to remove gvm. It also notes that upgrades from versions older than 0.0.8 can leave gvm's files in a mixed state. Before deleting anything, make sure you do not need the installed Go versions.

gvm implode rm -rf ~/.gvm

What people use it for

  • Building a project that needs an older Go release while other projects use a newer one.
  • Testing code against an older or newer Go version before a release.
  • Keeping per-project dependencies separate with package sets.
  • Installing a Go version from binary with -B when building from source is not practical.

Frequently asked questions

Does gvm work on Windows?

The README only documents requirements for Mac OS X, Linux and FreeBSD, so Windows is not covered. If you use Windows, check the project's documentation before relying on gvm.

What are gvm's prerequisites?

The README lists Bison, curl, git, Mercurial, gcc and make. Compiling Go from source needs gcc and make, and the exact packages depend on your operating system.

How do I install gvm?

Install Bison, then run the gvm-installer script from the moovweb/gvm repository with bash, or with zsh if you use zsh. The README gives the full command.

How do I switch between Go versions with gvm?

Install a version with gvm install, then run gvm use with that version. Add --default if you want it to be the default. Use gvm list to see which version is current.

How do I uninstall gvm?

Run gvm implode to remove gvm and all installed Go versions and packages. If that does not work, the README says rm -rf ~/.gvm will remove gvm.

Is gvm a good alternative to the official Go installer?

Only if you need several Go versions or per-project workspaces. The README says that if you only need one Go version, the official installer or a package manager is simpler because gvm adds setup overhead. Comparable projects include asdf, goenv and g.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

gvm suits developers who work on several projects that need different Go versions, or who want isolated package sets, and who are comfortable with the terminal. If you only need one Go version, or you want a graphical tool or native Windows support, the official installer, a package manager or another tool such as goenv, g or asdf is a better choice.

Install options & downloads