// Tutorial //

Understanding the GOPATH

Published on April 10, 2019
Understanding the GOPATH

This tutorial is out of date and no longer maintained.

Status: Deprecated

This article is deprecated and no longer maintained.


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.


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.


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:



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

Want to learn more? Join the DigitalOcean Community!

Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.

Sign up now

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?
Leave a comment...

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 here to sign up and get $200 of credit to try our products over 60 days!
Try DigitalOcean for free