The shell doesn't know where Go lives
You install Go. The installer finishes without errors. You open your terminal, type go version, and the shell replies with command not found: go. Or you try to run a simple program and get cannot find package "fmt". The installation worked. Your code is correct. The problem is that your terminal doesn't know where Go lives.
The operating system uses an environment variable called PATH to find executable programs. Think of PATH as a checklist of directories the shell scans whenever you type a command. When you type go, the shell walks through every folder in PATH looking for a file named go. If it finds one, it runs it. If it reaches the end of the list without success, it gives up. Installing Go places the binary on your disk, but it does not automatically add that folder to your PATH. You have to tell the shell where to look.
PATH is a search list. The shell searches it in order.
Quick fix: export for the session
You can update PATH immediately for the current terminal session. This change disappears when you close the window, but it lets you verify the fix works.
// main.go
package main
import "fmt"
// main is the entry point for the program.
func main() {
// Print a message to confirm Go can compile and run.
fmt.Println("Go is ready")
}
Run the program after updating the path.
# Append the Go bin directory to the existing PATH.
# This makes the go binary discoverable for this session.
export PATH=$PATH:/usr/local/go/bin
# Verify the toolchain is accessible.
go version
# Run the program.
go run main.go
The export command modifies the environment of the current shell process and any child processes it spawns. It does not change the file system. It changes the view the shell has of available commands. The shell updates its internal list. The next time you type go, the shell finds the binary in /usr/local/go/bin and executes it.
The shell doesn't guess. It searches.
Permanent fix: shell config
Real development requires a permanent fix. You need to add the export command to your shell's configuration file. The file depends on your shell. Use ~/.zshrc for Zsh, which is the default on modern macOS. Use ~/.bashrc or ~/.profile for Bash.
# Append the export command to your shell config.
# This ensures Go is available in every new terminal session.
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.zshrc
# Reload the config to apply changes immediately.
source ~/.zshrc
# Verify the path persists.
go version
The >> operator appends text to the end of the file. Using > overwrites the file and destroys your existing configuration. Always use >> when adding to a config file. After editing, run source to reload the file without closing the terminal. This applies the changes to the current session immediately.
Check your config file. One typo breaks the shell.
Go's environment: GOROOT and GOPATH
Go uses two environment variables to manage paths. GOROOT points to the Go installation directory. GOPATH points to your workspace where your code and dependencies live.
You rarely need to set GOROOT manually. The installer configures it automatically. If GOROOT is empty or wrong, your installation is broken. You can inspect the current values with go env.
# Display the current Go environment settings.
# This shows GOROOT, GOPATH, and other configuration details.
go env
# Check specifically for the installation root.
go env GOROOT
The output shows GOROOT=/usr/local/go on a standard installation. If GOROOT points to a non-existent directory, the toolchain cannot find the standard library. The compiler rejects programs with cannot find package "fmt" because it cannot locate the built-in packages.
GOPATH defaults to ~/go in modern Go. You don't need to set it unless you have a specific reason to use a different workspace. The convention is to let Go use its defaults. Setting GOPATH explicitly often causes more problems than it solves. The toolchain manages modules and dependencies automatically when GOPATH is left alone.
Trust go env. It reveals the truth.
Pitfalls and errors
Several issues can cause path-related failures. The shell rejects the command with command not found: go if the binary is missing from PATH. This happens when the export line is missing, the path is incorrect, or the config file hasn't been reloaded.
The Go toolchain reports cannot find package "fmt" if it cannot locate the standard library. This usually means GOROOT is misconfigured. It can also happen if the installation is incomplete or corrupted. Check go env GOROOT to verify the path points to a valid directory.
You might see go: command not found on some systems. This is the same as command not found. The shell cannot locate the executable.
Multiple Go installations can cause conflicts. If you have an old version in ~/bin and a new version in /usr/local/go/bin, the shell runs the first one it finds. The order in PATH matters. Directories listed earlier take precedence. Run which go to see which binary the shell is using. If the path is wrong, adjust the order in your config file or remove the conflicting installation.
# Show the full path of the go binary being used.
# This helps identify conflicts between installations.
which go
# List all go binaries found in PATH.
# This reveals hidden duplicates.
which -a go
Goroutines are cheap. Channels are not magic. PATH is just a list.
Decision: fixing the path
Use export PATH=... in your terminal when you need a quick fix for the current session. Use ~/.zshrc or ~/.bashrc when you want the change to persist across reboots and new windows. Use go env when you need to verify your configuration and diagnose path issues. Use a package manager like Homebrew when you want the tool to handle PATH updates automatically.
The worst goroutine bug is the one that never logs. The worst PATH bug is the one that only fails in new terminals.