Install Go Commands Without Surprising Your Module

You will install a Go command into a predictable directory, verify which binary you ran, and choose whether the install should use the current module. The go command on this machine reports Go 1.26.1 and is resolved from Linuxbrew; Debian's installed golang-go package is version 2:1.22~2build1. Check your own path and version rather than assuming those two installations are interchangeable. Allow about ten minutes, plus download time for a command and its dependencies. You need a shell, a working Go installation, and write access to the destination directory.

1. Check the Go tool and its destination

Start by checking the executable you are about to use and the settings that control where commands land:

$ go version
go version go1.26.1 linux/amd64
$ go env GOPATH GOBIN
/home/your-user/go

A blank second line means GOBIN is unset. In that case, Go installs ordinary executables in $GOPATH/bin, or in $HOME/go/bin when GOPATH is also unset. If you set GOBIN, it becomes the destination instead. Commands belonging to Go itself are placed under GOROOT or its tool directory, not your personal bin directory.

Checkpoint: ask Go for the effective values with names attached. This avoids confusing a blank value with a missing command:

$ go env GOBIN GOPATH GOROOT

/home/your-user/go
/usr/local/go

The paths above are examples. Use the paths printed by your own machine. You do not normally need sudo for a personal GOPATH/bin or GOBIN. Do not make a system directory writable merely to avoid fixing your PATH.

2. Install a command in the current module

When you are working on a module and want its declared dependencies and replacements to apply, run go install without a version suffix. A common repository layout puts commands below cmd:

$ cd /path/to/example-project
$ test -f go.mod && echo 'module found'
module found
$ go install ./cmd/example

The package must build a command, meaning its package name is main. With module-aware mode enabled, dependencies are compiled and cached, but ordinary dependency packages are not installed as separate files. The executable is the useful output.

Verify the result using the destination Go reports, rather than guessing its location:

$ command -v example
/home/your-user/go/bin/example
$ example --help
Usage: example [options]

Your command may use a different help option or output. If command -v finds nothing, inspect the directory directly:

$ ls -l "$(go env GOBIN 2>/dev/null || true)"
$ ls -l "$(go env GOPATH)/bin/example"

When GOBIN is set, the first check needs its actual printed value; an empty GOBIN is not a directory. A simpler check that works after resolving the destination is:

$ go env GOPATH
/home/your-user/go
$ test -x "$(go env GOPATH)/bin/example" && echo installed
installed

3. Install a pinned command without changing the project

For a tool you want to use across several repositories, add a version suffix. This makes Go use module-aware mode while ignoring go.mod in the current directory and its parents:

$ go install example.com/tool/cmd/[email protected]

Replace the path and version with a real command documented by its project. Use @latest only when accepting the newest available version is deliberate:

$ go install example.com/tool/cmd/example@latest

This is the modern replacement for using go get to install executables. A pinned version gives a repeatable input; @latest can move later, so record the chosen version if the tool is part of a build or incident-response procedure.

Version-suffixed installs have stricter rules. Arguments must be package paths or patterns, not a local path such as ./cmd/example, a standard package such as fmt, or a meta-pattern such as all. All arguments must use the same version suffix and must name main packages from the same module and version:

$ go install example.com/tool/cmd/[email protected] example.com/tool/cmd/[email protected]

Do not mix @latest with @v1.4.2, or commands from unrelated modules. The command may download source from the network and execute build steps supplied by dependencies. Review the module and version before running it, particularly on a production or privileged workstation.

4. Make the installed command discoverable

The install can succeed while your shell still reports "command not found" because the destination is absent from PATH. Print the two relevant values:

$ printf 'GOBIN=%s\nGOPATH=%s\n' "$(go env GOBIN)" "$(go env GOPATH)"
GOBIN=
GOPATH=/home/your-user/go
$ printf '%s\n' "$PATH" | tr ':' '\n' | grep -Fx "$(go env GOPATH)/bin"
/home/your-user/go/bin

If the final command prints nothing, add the correct directory to the shell startup file used by your login shell. For a Bash login setup, append one line to ~/.profile with your real path:

export PATH="$PATH:$HOME/go/bin"

Start a new login shell, or source that file, then verify again with command -v example. If you use a custom GOBIN, add that directory instead. Keep the setting consistent between interactive shells, scripts and services; a service often has a deliberately smaller PATH.

5. Handle failures without leaving a misleading binary

If compilation fails, read the first useful error and fix the source, module version or platform assumption it identifies. A failed install should not be treated as proof that an older binary was replaced. Check the file timestamp and version command before relying on it:

$ command -v example
/home/your-user/go/bin/example
$ example --version
example version 1.4.2

Shell redirection is not part of go install, but it is a common trap when testing a command's output. Do not pipe an untrusted installer into a root shell, and do not run go install with sudo just because the command is missing from PATH. If you intentionally installed into a disposable custom directory and want to undo it, remove only the exact executable after checking its path:

$ command -v example
/home/your-user/go/bin/example
$ rm -- /home/your-user/go/bin/example

That removal is irreversible for the binary, although you can reinstall the same version. Do not use a wildcard in the removal command. Go's build cache is separate and can normally be left alone; clearing it is not a repair for a command that is simply hidden by PATH.