What does go build build? (go build vs. go install)

New Go programmers often don't know or get confused what the fundamental go build command does.

What do exactly the go build and go install commands build and where do they put the result/output?

What the go command does depends on whether we run it for a "normal" package or for the special "main" package.

For packages

• go build   builds your package then discards the results.
• go install builds then installs the package in your $GOPATH/pkg directory.

For commands (package main)

• go build   builds the command and leaves the result in the current working directory.
• go install builds the command in a temporary directory then moves it to $GOPATH/bin.

What to pass to go build?

You may pass packages to go build, packages you want to build. You may also pass a list of .go files from a single directory, which is then treated as the list of source files specifying a single package.

If no packages (import paths) are provided, the build is applied on the current directory.

An import path may contain one or more "..." wildcards (in which case it is a pattern). ... can match any string, e.g. net/... matches the net package and packages being in any of its subfolders. The command

go build ./...

often used to build the package in the current folder and all packages recursing down. This command issued in a project root builds the complete project.

For more about specifying packages, run go help packages.

Regarding modules

Preliminary support for Go modules was introduced in Go 1.11, and modules became default starting with Go 1.13. When the go tool is run from a folder which contains a go.mod file (or one of the parents of the current folder), the go tool runs in module-aware mode (the legacy mode is called GOPATH mode).

> In module-aware mode, GOPATH no longer defines the meaning of imports during a build, but it still stores downloaded dependencies (in GOPATH/pkg/mod) and installed commands (in GOPATH/bin, unless GOBIN is set).

When building modules, what is built is specified by the build list. The build list initially contains only the main module (the module containing the directory where the go command is run), and the dependencies of the main module are added to the build list, recursively (dependencies of dependencies are also added).

For more info, run go help modules.

---

Basically you can use go build as a check that the packages can be built (along with their dependencies) while go install also (permanently) installs the results in the proper folders of your $GOPATH.

go build will silently terminate if everything is OK, and will give you error messages if the packages cannot be built/compiled.

Whenever the go tool installs a package or binary, it also installs whatever dependencies it has, so running go install will also install packages your program depends on (publicly available, "go gettable" packages), automatically.

For a start, read the official How to Write Go Code page.

More information about the go tool: Command go

You can also get more help by running the following command:

go help build

It is also worth noting that starting with Go 1.5 go install also removes executables created by go build (source):

> If 'go install' (with no arguments, meaning the current directory) succeeds, remove the executable written by 'go build', if present. This avoids leaving a stale binary behind...

To complete the list, go run compiles your application into a temporary folder, and starts that executable binary. When the app exits, it properly cleans up the temporary files.

_{Question inspired by Dave Cheney's What does go build build?}

For package:

> go build: builds your package then discards the results

That won't be true after Go 1.10 (Q1 2018), thank to CL 68116 and CL 75473. See this thread, that I reference here.

> > What do exactly the go build and go install commands build

> Whenever the go tool installs a package or binary, it also installs whatever dependencies it has, so running go install will also install packages your program depends on (publicly available, "go gettable" packages), automatically.

Actually... go install will change also with Go 1.10, in addition of the new cache:

> The "go install" command no longer installs dependencies of the named packages (CL 75850).

> If you run "go install foo", the only thing installed is foo.

> Before, it varied. If dependencies were out-of-date, "go install" also installed any dependencies.
The implicit installation of dependencies during "go install" caused a lot of confusion and headaches for users, but it was previously necessary to enable incremental builds.
Not anymore.
We think that the new "install what I said" semantics will be much more understandable, especially since it's clear from bug reports that many users already expected them.
To force installation of dependencies during "go install", use the new "go install -i", by analogy with "go build -i" and "go test -i".

> The fact that "go install" used to install any rebuilt dependencies caused confusion most often in conjunction with -a, which means "force rebuild of all dependencies".
Now, "go install -a myprog" will force a complete rebuild of all dependencies of myprog, as well as myprog itself, but only myprog will get installed. (All the rebuilt dependencies will still be saved in the build cache, of course.)
Making this case work more understandably is especially important in conjunction with the new content-based staleness analysis, because it sees good reasons to rebuild dependencies more often than before, which would have increased the amount of "why did my dependencies get installed" confusion.
For example, if you run "go install -gcflags=-N myprog", that installs a myprog built with no compiler optimizations, but it no longer also reinstalls the packages myprog uses from the standard library without compiler optimizations.