Users need a simple, easy-to-remember way to install Go programs. Similarly, tool authors need a short one-liner they
can include at the top of their
README.md explaining how to install the tool.
Go 1.16 introduces a new way to install Go programs directly with the
go command. This guide
introduces the new mode of
go install using the example of
filippo.io/mkcert, and is suitable for both end users and tool authors.
You should already have completed:
This guide is running with:
$ go version go version go1.16 linux/amd64
Currently, tool authors who want to provide installation instructions in their projects’
README.md typically include:
$ go get email@example.com go: downloading filippo.io/mkcert v1.4.2 go: downloading golang.org/x/net v0.0.0-20190620200207-3b0461eec859 go: downloading golang.org/x/tools v0.0.0-20191108193012-7d206e10da11 go: downloading honnef.co/go/tools v0.0.0-20191107024926-a9480a3ec3bc go: downloading howett.net/plist v0.0.0-20181124034731-591f970eefbb go: downloading software.sslmate.com/src/go-pkcs12 v0.0.0-20180114231543-2291e8f0f237 go: downloading golang.org/x/text v0.3.0 go: downloading github.com/BurntSushi/toml v0.3.1
README.md instructions that use
go get do not specify a version. This results in the latest
version of a package being fetched. A specific version,
v1.4.2, is used here to ensure this guide
There are a number of problems with this approach:
- A user might run the above
go getwithin a module, which would update the current module’s dependencies, rather than just installing the tool directly.
go getmight not be running in module mode at all, for example if the user previously modified
- The use of
go getis confusing; it is used to download and install executables, but it’s also responsible for managing dependencies in
Prior to Go 1.16, the general advice to fix the first two problems was to use a snippet
go get in module mode and outside any module, by using a temporary directory:
$ (cd $(mktemp -d); GO111MODULE=on go get firstname.lastname@example.org)
However, this new approach had its own problems:
- It’s not user-friendly; the extra shell is confusing to newcomers, and hard to remember.
- It’s not cross platform; the command is not guaranteed to work on Windows.
It is clear that neither method is satisfactory, especially for
instructions which are meant to be brief and easy to follow.
go install in Go 1.16
In Go 1.16, the
go install command is now used to install programs directly, i.e. regardless of the current
$ go install email@example.com
For the purposes of this guide you are using a specific version (
latest version can be used to install the latest release.
Much like the previous behaviour of
go install places binaries in
$GOBIN if set. See the “Setting up your
PATH“ section in Installing Go to ensure
PATH is set correctly.
mkcert is now on your
$ which mkcert /home/gopher/go/bin/mkcert
mkcert to check everything is working:
$ mkcert -version v1.4.2
You can also use
go version to see the module dependencies used in building the program:
$ go version -m $(which mkcert) /home/gopher/go/bin/mkcert: go1.16 path filippo.io/mkcert mod filippo.io/mkcert v1.4.2 h1:7mWofpFS4gzQS5bhE3KYBwzfceIPy2KJ4tMT31aPNeY= dep golang.org/x/net v0.0.0-20190620200207-3b0461eec859 h1:R/3boaszxrf1GEUWTVDzSKVwLmSJpwZ1yqXm8j0v2QI= dep golang.org/x/text v0.3.0 h1:g61tztE5qeGQ89tm6NTjjM9VPIm088od1l6aSorWRWg= dep software.sslmate.com/src/go-pkcs12 v0.0.0-20180114231543-2291e8f0f237 h1:iAEkCBPbRaflBgZ7o9gjVUuWuvWeV4sytFWg9o+Pj2k=
To eliminate redundancy and confusion, using
go get to build or
install programs is being deprecated in Go 1.16.
That’s it! Time to sit back and wait for the release of Go 1.16!
As a next step you might like to consider: