Tutorial

Understanding the GOPATH

Published on April 10, 2019
English
Understanding the GOPATH

This tutorial is out of date and no longer maintained.

Status: Deprecated

This article is deprecated and no longer maintained.

Reason

Beginning with Go v1.13, the authors of Go added a new way of managing the libraries a Go project depends on, called Go modules. Using modules is the current method for maintaining dependencies and managing Go project structures. Understanding the GOPATH may still be relevant, but modules have replaced GOPATH in most cases for day-to-day usage.

Also, the Go Workspace mentioned in this tutorial is different from the multi-module workspace released with Go v1.18. For more information on the current Go workspaces, see the Go product documentation for workspaces.

See Instead

This article may still be useful as a reference, but may not work or follow best practices. We strongly recommend using a recent article written for the operating system you are using.

Introduction

This article will walk you through understanding what the GOPATH is, how it works, and how to set it up. This is a crucial step for setting up a Go development environment, as well as understanding how Go finds, installs, and builds source files. In this article we will use GOPATH when referring to the concept of the folder structure we will be discussing. We will use $GOPATH to refer to the environment variable that Go uses to find the folder structure.

A Go Workspace is how Go manages our source files, compiled binaries, and cached objects used for faster compilation later. It is typical, and also advised, to have only one Go Workspace, though it is possible to have multiple spaces. The GOPATH acts as the root folder of a workspace.

Setting the $GOPATH Environment Variable

The $GOPATH environment variable lists places for Go to look for Go Workspaces.

By default, Go assumes our GOPATH location is at $HOME/go, where $HOME is the root directory of our user account on our computer. We can change this by setting the $GOPATH environment variable. For further study, follow this tutorial on reading and setting environment variables in Linux.

For more information on setting the $GOPATH variable, see the Go documentation.

Furthermore, this series walks through installing Go and setting up a Go development environment.

$GOPATH Is Not $GOROOT

The $GOROOT is where Go’s code, compiler, and tooling lives — this is not our source code. The $GOROOT is usually something like /usr/local/go. Our $GOPATH is usually something like $HOME/go.

While we don’t need to specifically set up the $GOROOT variable anymore, it is still referenced in older materials.

Now, let’s discuss the structure of the Go Workspace.

Anatomy of the Go Workspace

Inside of a Go Workspace, or GOPATH, there are three directories: bin, pkg, and src. Each of these directories has special meaning to the Go tool chain.

.
├── bin
├── pkg
└── src
  └── github.com/foo/bar
    └── bar.go

Let’s take a look at each of these directories.

The $GOPATH/bin directory is where Go places binaries that go install compiles. Our operating system uses the $PATH environment variable to find binary applications that can execute without a full path. It is recommended to add this directory to our global $PATH variable.

For example, if we don’t add $GOPATH/bin to $PATH to execute a program from there, we would need to run:

  1. $GOPATH/bin/myapp

When $GOPATH/bin is added to $PATH we can make the same call like such:

  1. myapp

The $GOPATH/pkg directory is where Go stores pre-compiled object files to speed up subsequent compiling of programs. Typically, most developers won’t need to access this directory. If you experience issues with compilation, you can safely delete this directory and Go will then rebuild it.

The src directory is where all of our .go files, or source code, must be located. This shouldn’t be confused with the source code the Go tooling uses, which is located at the $GOROOT. As we write Go applications, packages, and libraries, we will place these files under $GOPATH/src/path/to/code.

What Are Packages?

Go code is organized in packages. A package represents all the files in a single directory on disk. One directory can contain only certain files from the same package. Packages are stored, with all user-written Go source files, under the $GOPATH/src directory. We can understand package resolution by importing different packages.

If our code lives at $GOPATH/src/blue/red then its package name should be red.

The import statement for the red package would be:

import "blue/red"

Packages that live in source code repositories, like GitHub and BitBucket, have the full location of the repository as part of their import path.

For example, we would import the source code at https://github.com/gobuffalo/buffalo using the following import path:

import "github.com/gobuffalo/buffalo"

Therefore, this source code would be in the following location on disk:

$GOPATH/src/github.com/gobuffalo/buffalo

Conclusion

In this article we discussed the GOPATH as a set of folder’s that Go expects our source code to live within, as well as what those folders are, and what they contain. We discussed how to change that location from the default of $HOME/go to the user’s choice by setting the $GOPATH environment variable. Finally, we discussed how Go searches for packages within that folder structure.

Introduced in Go 1.11, Go Modules aim to replace Go Workspaces and the GOPATH. While it is recommended to start using modules, some environments, such as corporate environments, may not be ready to use modules.

The GOPATH is one of the trickier aspects of setting up Go, but once it is set up, we can usually forget about it.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us


Tutorial Series: How To Code in Go

Go (or GoLang) is a modern programming language originally developed by Google that uses high-level syntax similar to scripting languages. It is popular for its minimal syntax and innovative handling of concurrency, as well as for the tools it provides for building native binaries on foreign platforms.

About the authors


Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
1 Comments


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Very Helpful!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel