Introduction

The GOPATH environment variable is used to specify directories outside of $GOROOT that contain the source for Go projects and their binaries.

GOPATH is used by goinstall and the "go" tool as a destination for the binaries it builds and a location to search for imports.

GOPATH is a path list - multiple directories can be specified by separating them with a ":" (on os x or linux) or a ";" (on windows). When multiple directories are listed, and goinstall or "go" are used from outside any of them, the first directory is used as the installation destination. When using either tool from within one of the listed directories, the containing directory is used as the installation destination.

For most of this document, $GOPATH will refer to whichever of the listed directories is the currently active one.

Integrating GOPATH

On os x or linux, adding the following expression to PATH will add all $GOPATH/bin directories.

${GOPATH//://bin:}/bin

Adding the following block to a standard Go makefile will bring in all $GOPATH pkg directories.

GOPATHSEP=:
ifeq ($(GOHOSTOS),windows)
GOPATHSEP=;
endif
GCIMPORTS+=-I $(subst $(GOPATHSEP),/pkg/$(GOOS)_$(GOARCH) -I , $(GOPATH))/pkg/$(GOOS)_$(GOARCH)
LDIMPORTS+=-L $(subst $(GOPATHSEP),/pkg/$(GOOS)_$(GOARCH) -L , $(GOPATH))/pkg/$(GOOS)_$(GOARCH)

goinstall and the "go" tool already know about GOPATH.

Directory layout

The source for a package with the import path "X/Y/Z" is in the directory

$GOPATH/src/X/Y/Z

The binary for a package with the import path "X/Y/Z" is in

$GOPATH/pkg/$GOOS_$GOARCH/X/Y/Z.a

The binary for a command whose source is in $GOPATH/src/A/B is

$GOPATH/bin/B

repository integration and creating "goinstallable" projects

goinstall, when fetching a package, looks at the package's import path to discover a URL. For instance, if you attempt to

goinstall code.google.com/p/gomatrix/matrix

goinstall will get the source from the project hosted at http://code.google.com/p/gomatrix, and it will clone the repository to

$GOPATH/src/code.google.com/p/gomatrix

As a result, if (from your repository project) you import a package that is in the same repository, you need to use its "full" import path - the place goinstall puts it. In this example, if something else wants to import the "matrix" package, it should import "code.google.com/p/gomatrix/matrix" rather than "matrix".

If you prefer to use makefiles to build on your own machine and you still want your project to work well with goinstall, set the TARG variable to the long import path. goinstall will ignore this makefile, but as long as TARG matches the package's location relative to the repository, goinstall will choose the same import path.

Tips and tricks

Third-party Packages

It is useful to have two GOPATH entries. One for a location for 3rd party goinstalled packages, and the second for your own projects. List the 3rd party GOPATH first, so that goinstall will use it as a default destination. Then you can work in the second GOPATH directory and have all your packages be importable by using the "go" command, goinstall, or a GOPATH-aware 3rd party build tool like gb.

FAQ

Why won't $GOPATH/src/cmd/mycmd/*.go build?

When the go command is looking for packages, it always looks in $GOROOT first. This includes directories, so if it finds (as in the case above) a cmd/ directory in $GOROOT it won't proceed to look in any of the GOPATH directories. This prevents you from defining your own math/matrix package as well as your own cmd/mycmd commands.