4. Go Environment

Let's clear up a few points before you start writing Go locally.

Directory Structure

To recap how packages and modules work in your project directory structure:

• You will have many git repositories on your machine (typically one per project).

• Each repository is typically a single module.

• Each module contains one or more packages.

• Each package consists of one or more Go source files in a single directory.

The path to a package's directory determines its import path and where it can be downloaded from if you decide to host it on a remote version control system like GitHub or GitLab.

A Note About GOPATH

The $GOPATH environment variable will be set by default somewhere on your machine (typically ~/go). Since we will be working in the new "Go modules" setup, you don't need to worry about that. If you read something online about setting up your GOPATH, that documentation is probably out of date.

These days you should avoid working in the $GOPATH/src directory. That's the old way of doing things and can cause unexpected issues, so better to just avoid it.

Get Into Your Workspace

Navigate to a location on your machine where you want to store some code. For example, one approach is to store all code in ~/workspace, then organize it into subfolders based on the remote location. For example:

~/workspace/github.com/wagslane/go-password-validator = https://github.com/wagslane/go-password-validator

That said, you can put your code wherever you want.

Directory Organization Hierarchy

Machine
└── Workspace (e.g., ~/workspace or ~/projects)
    └── Repository (git repo, one per project)
        └── Module (go.mod file, usually one per repo)
            └── Package 1 (directory)
                ├── file1.go
                └── file2.go
            └── Package 2 (directory)
                └── file3.go

Typical Setup

Your workspace structure:

~/workspace/
├── github.com/
│   ├── myusername/
│   │   ├── project1/          ← One repository
│   │   │   ├── go.mod         ← One module
│   │   │   ├── main.go        ← Package main
│   │   │   └── utils/         ← Package utils
│   │   │       └── helpers.go
│   │   │
│   │   └── project2/          ← Another repository
│   │       ├── go.mod
│   │       └── main.go
│   │
│   └── someoneelse/
│       └── theirproject/

Organizing by Remote Location

Mirror the remote URL structure locally:

Remote:

https://github.com/wagslane/go-password-validator

Local:

~/workspace/github.com/wagslane/go-password-validator/

Benefits:

• Easy to find projects

• Matches import paths

• Organized by source

GOPATH - Ignore It

Old way (deprecated):

~/go/src/github.com/user/project  ❌ Don't do this

New way (modules):

~/workspace/github.com/user/project  ✓ Do this

Key point: Avoid $GOPATH/src directory. Work anywhere else on your machine.

What is GOPATH?

• Environment variable (usually ~/go)

• Used in old Go versions (pre-modules)

• You don't need to set it or use it

• Modern Go modules work anywhere

Setting Up a Project

Navigate to your workspace

cd ~/workspace

Create project directory

mkdir -p github.com/myusername/myproject
cd github.com/myusername/myproject

Initialize module

go.mod

go mod init github.com/myusername/myproject

This creates `go.mod`:

```text
module github.com/myusername/myproject

go 1.25.1

{% endstep %}

{% step %}

Write code

# Create main.go, add packages, etc.

{% endstep %} {% endstepper %}

Example: Real Project Structure

~/workspace/github.com/bootdotdev/bankapp/
├── go.mod
├── main.go
├── customer/
│   ├── customer.go
│   └── account.go
└── transaction/
    └── transaction.go

Import paths match directory structure:

import "github.com/bootdotdev/bankapp/customer"
import "github.com/bootdotdev/bankapp/transaction"

Where to Put Your Code

Option 1: Mirror remote (recommended)

~/workspace/github.com/username/project/

Option 2: Flat structure

~/projects/project1/
~/projects/project2/

Option 3: Whatever you want

~/code/myproject/
~/dev/bankapp/

All work with Go modules — the location doesn't matter anymore.

Quick Reference

Concept	Example	Notes
Workspace	~/workspace	Where you store code
Repository	~/workspace/github.com/user/project	One project
Module	go.mod in repo root	Defined by go.mod
Package	customer/ subdirectory	Directory with .go files
GOPATH	~/go	Ignore it, don't use it

Commands to Get Started

# Navigate to workspace
cd ~/workspace

# Create project structure
mkdir -p github.com/myname/myproject
cd github.com/myname/myproject

# Initialize module
go mod init github.com/myname/myproject

# Create a Go file
touch main.go

# Run it
go run main.go

Key Takeaways

1. Work anywhere — modules work in any directory

2. Avoid GOPATH/src — that's the old way

3. Mirror remote structure — optional but organized

4. One repo = one module — typical setup

5. go.mod defines module — always at repo root

6. Subdirectories = packages — each directory is a package

Bottom line: Put your code anywhere outside $GOPATH/src, initialize with go mod init, and you're good to go!