The shell doesn't know where Go lives
You downloaded the Go installer, clicked through the setup, and closed the window. You open your terminal, type go version, and hit enter. The shell responds with go: command not found. The installation succeeded. The binary exists somewhere on your disk. Your shell just doesn't know where to look.
This error happens because the Go binary directory is missing from your system's PATH environment variable. The fix is to add that directory to the list of places the shell searches for commands. Once you update the PATH and reload your shell, the command works.
How the shell finds commands
Your operating system uses an environment variable called PATH to locate executables. PATH is a string containing a list of directories separated by a delimiter. On macOS and Linux, the delimiter is a colon. On Windows, it is a semicolon.
When you type a command, the shell splits the PATH string into a list of folders and checks each one in order. If it finds an executable file matching the command name, it runs it. If it reaches the end of the list without a match, it prints the error.
Think of PATH like a set of labeled drawers in a workshop. You ask for a wrench. The assistant checks the "Tools" drawer, then the "Hardware" drawer, then the "Electronics" drawer. If the wrench is sitting in a box on the floor, the assistant never finds it. Go installs its binaries in a specific folder. On macOS and Linux, that folder is usually /usr/local/go/bin. On Windows, it is C:\Program Files\Go\bin. If that folder isn't in your list of drawers, the shell can't find Go.
The shell searches the list. Update the list.
Quick fix for the current session
You can update the PATH immediately by exporting a new value. This change applies only to the current terminal window. If you close the window, the change disappears.
# Append the Go binary directory to the existing PATH.
# The shell reads PATH from left to right, so appending keeps
# system tools taking precedence while adding Go to the search list.
# On macOS and Linux, use a colon to separate directories.
export PATH="$PATH:/usr/local/go/bin"
On Windows PowerShell, the syntax differs slightly. The delimiter is a semicolon, and you modify the environment variable directly.
# Append the Go binary directory to the existing PATH in PowerShell.
# Use a semicolon as the separator.
# This updates the variable for the current session only.
$env:PATH += ";C:\Program Files\Go\bin"
After running the command, verify the fix by typing go version. The terminal should print the installed version number, like go version go1.22.0 darwin/arm64. If you still see the error, check the path in your command. A typo in the directory name causes the shell to skip the folder.
Verify with go version before you write a single line of code.
Making the change permanent
The export command vanishes when the terminal closes. To make the change stick, you need to write the command into a shell configuration file. Shells read these files every time a new session starts.
The file you need depends on your shell. macOS uses zsh by default since Catalina. Linux distributions vary; Ubuntu often uses bash, while Arch may use zsh. Run echo $SHELL to see which shell your system uses.
For zsh, add the export line to ~/.zshrc.
# Append the export command to the zsh configuration file.
# The >> operator appends to the file without overwriting existing content.
# Quoting the string prevents the shell from expanding $PATH during the echo.
echo 'export PATH="$PATH:/usr/local/go/bin"' >> ~/.zshrc
# Reload the configuration file to apply the change immediately.
# This avoids closing and reopening the terminal.
source ~/.zshrc
For bash, the file is usually ~/.bashrc or ~/.profile. Some systems read ~/.bashrc only for interactive shells, while ~/.profile runs for login shells. Adding the line to ~/.bashrc works for most development workflows.
# Append the export command to the bash configuration file.
# Use ~/.bashrc for interactive shells on most Linux distros.
echo 'export PATH="$PATH:/usr/local/go/bin"' >> ~/.bashrc
# Reload the file to apply the change.
source ~/.bashrc
On Windows, PowerShell does not use a simple text file for persistent environment variables in the same way. You can use the Setx command to update the user-level PATH permanently, or use the System Properties GUI.
# Use Setx to update the user-level PATH permanently.
# Setx writes to the registry, so the change persists across reboots.
# This command opens a new session to apply the change.
Setx PATH "%PATH%;C:\Program Files\Go\bin"
Source the config or restart the terminal.
Common pitfalls and errors
Adding Go to the PATH is simple, but a few mistakes cause subtle failures.
Prepending the Go path instead of appending can shadow system binaries. If you set PATH="/usr/local/go/bin:$PATH", the shell checks the Go directory first. If a future Go release includes a binary with the same name as a system tool, the shell runs the Go version instead. Always append to keep system tools safe.
Spaces in paths break unquoted assignments. If your Go installation lives in a folder with a space, like My Go Projects, and you forget quotes, the shell splits the path at the space. The result is a malformed PATH that points to non-existent directories. The shell might complain with bad substitution or simply fail to find the command. Always quote the PATH assignment.
On Windows, forgetting the semicolon merges the last directory with the Go path. If you append C:\Program Files\Go\bin without a semicolon, the PATH ends with ...existing_pathC:\Program Files\Go\bin. The shell treats this as one long directory name, which doesn't exist. Both the existing path and the Go path break. Always include the separator.
If you mess up the syntax, the compiler isn't involved yet. The shell rejects the command with errors like export: not valid identifier or bad pattern. If the PATH becomes corrupted, you might see command not found for basic tools like ls or cd. In that case, open a fresh terminal and fix the config file.
The shell trusts the list. Garbage in the list means garbage out.
Verifying the environment
Once the PATH is set, use Go's built-in tool to inspect the environment. Run go env to see all the variables Go uses.
# Display the Go environment variables.
# Look for GOROOT to confirm Go knows where it is installed.
# Look for GOPATH to see where Go stores your modules and caches.
go env
The output shows GOROOT, which points to the Go installation directory. If GOROOT is empty or points to a weird location, your PATH might be pointing to the wrong folder. The GOPATH variable tells you where Go expects to find your code. By default, this is your home directory under a go folder.
You can also use which go on macOS and Linux, or where go on Windows, to see exactly which binary the shell finds.
# Show the full path to the go binary the shell will execute.
# This confirms the PATH is pointing to the correct installation.
which go
If which go returns /usr/local/go/bin/go, your setup is correct. If it returns nothing, the PATH is still missing the directory.
Trust go env. It tells you what Go sees.
When to use which approach
Use export PATH="$PATH:/usr/local/go/bin" when you need a quick fix for the current terminal session. Use the export line in ~/.zshrc or ~/.bashrc when you want the change to persist across reboots on macOS or Linux. Use Setx or the System Properties GUI when you are on Windows and need a permanent environment variable update. Run go env when you suspect Go is installed but the environment variables are misconfigured. Reinstall Go using the official installer when the binary is missing entirely from the disk.
The worst goroutine bug is the one that never logs. The worst PATH bug is the one that breaks your shell. Test carefully.