Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
  1. Code
  2. Go

Let's Go: Golang Code Organization


Go is a special language among modern languages. It is very opinionated. For example, there is one true formatting. Go will tell you how to space your code and where to put your curly braces. But it goes much deeper than that. 

Go will also tell you how to capitalize your functions and variables to make them public or private. It will dictate the directory structure of your code. This may come as a surprise for developers coming to Go from more liberal programming languages. 

In this article, I'll explore some of Go's restrictions, discuss their merits, and suggest options for common situations.

Go is an incredibly powerful programming language, learn everything from writing simple utilities to building scalable, flexible web servers in our full course.

Project Euler

When I started learning Go, I created a solution to Problem #6 and just put it in a sub-directory alongside solutions to other problems in other languages. See Project Euler.

The issue is that Go doesn't want you to just scatter Go files randomly all over the place. I later realized that while it works in very simple cases where you don't import other packages, it is not proper.


Every non-trivial program is composed of multiple files or modules or components or classes. I'll just use "file" as a general term. They are often grouped in libraries or packages or assemblies. I'll just use "package" as a general term. The code you write depends on code in other files and packages. 

You need to tell your code how to find those packages and files in order to use their functionality. Each language has its own term: import, include, require. I'll just use "import" as a general term.

Some languages (or language specific tools) also allow you to install dependencies from a remote package repository and install them into a standard local location you can import from.

In most common programming languages, you have a lot of freedom. In C/C++, you tell the compiler/linker where the files and static libraries are (using command-line switches or environment variables like INCLUDE_DIR). In Python, you can install packages from PyPI using setup.py or with pip from PyPI and remote source control repositories. You then import based on the sys.path package search path.

The Go Way

Go, as always, is more prescriptive. It may offend your creativity that you don't get as much say about where to place things, but at the end of the day it doesn't really matter, and there is enough flexibility to accommodate various situations.

Go requires that you put your code in a workspace. A workspace is just a directory with three sub-directories: src, pkg, and bin. It is recommended that you keep all your projects under a single workspace. This way they can depend on each other and share common third-party packages.

Note: I currently work on Windows and use PowerShell for many of the interactive examples. For the following section, I wanted to show the directory structure of my workspace using the tree command. Windows has its own tree.exe command, but it is very limited (no levels). There is allegedly a full-fledged tree command for Windows here

But the site was unreachable. I ended up firing a Docker container running Ubuntu, mounting my Go workspace as /docs/Go, and using the Linux tree command to show it. So don't be confused if you see a Linux environment showing Windows directories and files with .exe suffixes.

Here is my current Go workspace. The bin directory contains various Go commands/tools, and the delve debugger. The pkg dir has a sub-directory with the platform (Win 64) that contains the packages organized by their origin (github.com, golang.com, etc.). The src directory has similar sub-directories for the origin repository or website (github.com, golang.org, etc.).

Let's take a look inside one of the source projects I created under src: the go-web-crawler. It is pretty simple here: just a flat list of Go files, a license, and a README file.


Two environment variables control your destiny in the land of Go. GOROOT is where the Go installation is:

Note that the Go root directory looks like a superset of a workspace with the src, bin, and pkg directories.

GOPATH points to your workspace. That's how Go finds your code.

There are a bunch of other Go related environment variables, many of which you were required to set in the past (e.g. GOOS and GOARCH). Now, they are optional, and you should not mess with them unless you really need to (e.g. when cross-compiling). To see all the Go environment variables, type: go env.

Installs and Imports

When you create a Go program or a library, you can install it. Programs go to your workspace's bin directory, and libraries go to the workspace's pkg directory. On Windows, I discovered that your %GOPATH%/bin is not in the %PATH% directory, so Windows couldn't find my executable. I added it to the Windows PATH and everything worked. Here is how to check in PowerShell that your PATH contains your workspace bin directory:

Let's see all that in action.

If I go to my go-web-crawler directory and type go install then go-web-crawler.exe is created in c:\Users\the_g\Documents\Go\bin:

I can now run it from my Go web crawler from anywhere.

Multiple Go Environments

That's all fine, but sometimes life is not so simple. You may want to have multiple separate workspaces. What's more, you may want to have multiple installations of Go (e.g. different versions) and multiple workspaces for each one. You can do this by dynamically setting GOPATH for changing the workspace and setting GOROOT for changing the active Go installation.

There are various open-source projects for vendoring, package management, and virtual environments. For some reason, most don't support Windows. I'm not sure why such tools have to be platform-specific. I may write a cross-platform Go environment manager myself one of these days.


Go is all about eliminating incidental complexity. Sometimes it comes off as very strict and prescriptive. But if you get into the mindset of the Go designers, you start to understand that avoiding, forbidding or mandating certain things really makes everything simpler.

Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.