The missing piece in your terminal
You write a small command line tool in Go. It works perfectly on your machine. You want to run it from any directory without typing go run ./cmd/tool. You also want to share it with a teammate who just needs the executable, not your entire source tree. You need a command that fetches dependencies, compiles the code, and drops the finished binary somewhere your shell can find it. That command is go install.
What go install actually does
go install is the standard way to turn a Go package into a standalone executable on your system. It performs three distinct steps in sequence. First, it resolves and downloads every dependency the package requires. Second, it compiles the package into a binary tailored to your operating system and CPU architecture. Third, it moves that binary to a designated installation directory. The command never touches your current working directory. It leaves your source tree completely alone. It only produces a compiled artifact.
Think of it like a factory assembly line. You hand the factory a blueprint using a module path. The factory orders all the raw materials from suppliers, assembles the machine on the production floor, and ships the finished product to your warehouse. You never see the raw materials or the assembly line. You just get the tool.
The command relies on Go's module system to handle dependency resolution. It talks to the Go module proxy, downloads the exact source code needed, compiles it using the local build cache, and places the result in your $GOBIN directory. If you run the exact same command again, the toolchain skips the network and compilation steps entirely. It just copies the cached binary to the destination. This makes repeated installations nearly instantaneous.
go install is purely a consumption command. It does not create a go.mod file in your current directory. It does not modify your local code. It is designed for installing tools, not for developing them.
The factory ships the product. You just run it.
Your first installation
Here is the simplest way to install a widely used Go tool. The goimports utility automatically adds and removes import statements in your Go files. It lives in the official golang.org/x/tools repository.
# Fetch the module, compile it, and drop the binary into $GOBIN
go install golang.org/x/tools/cmd/goimports@latest
The @latest suffix tells the Go toolchain to fetch the most recent tagged release. The toolchain contacts the module proxy, downloads the source, compiles it, and places the resulting goimports executable in your installation directory. You can then run goimports directly from any terminal window.
If you need a specific release instead of the newest one, replace @latest with the exact version tag.
# Pin to a known stable release for reproducible builds
go install golang.org/x/tools/cmd/goimports@v0.12.0
Version pinning matters when you share tooling across a team. Everyone gets the exact same binary behavior. The module proxy guarantees that v0.12.0 always points to the same commit, even if the repository maintainer pushes new code later.
Pin your tools. Reproducibility beats convenience.
Where the binary lands
Go needs a place to store installed binaries. That location is controlled by the $GOBIN environment variable. If $GOBIN is empty, Go falls back to $GOPATH/bin. The $GOPATH variable itself defaults to ~/go on Unix systems and %USERPROFILE%\go on Windows. This means your binaries usually land in ~/go/bin unless you configure otherwise.
You can verify your current installation directory with a single command.
# Show where Go will place the next installed binary
go env GOBIN
If the output is blank, Go is using the default $GOPATH/bin path. You can override this by exporting $GOBIN before running the install command.
# Point Go to a custom directory that you control
export GOBIN=$HOME/.local/bin
go install github.com/youruser/mytool/cmd/mytool@main
Go does not automatically add $GOBIN to your system PATH. You must wire it up yourself. Open your shell configuration file, usually ~/.bashrc or ~/.zshrc, and append the directory to the PATH variable.
# Append the Go binary directory to your shell's search path
export PATH="$HOME/go/bin:$PATH"
Restart your terminal or run source ~/.bashrc to apply the change. Once the directory is in your PATH, your shell finds the executable without needing the full file path. This convention applies to every programming language that distributes CLI tools. Go just expects you to manage the environment variable yourself.
Wire up your PATH once. Forget about it forever.
Picking exact versions and branches
Modern Go requires a version suffix on every go install command. This rule exists to prevent accidental upgrades and to guarantee that builds are reproducible. If you omit the suffix, the compiler rejects the command immediately.
# This will fail in module-aware mode
go install golang.org/x/tools/cmd/goimports
The toolchain responds with go install: version required: update module path to include a version. You must add @latest, @v1.2.3, @main, or a specific commit hash.
Branch names work exactly like version tags. You can install from the main branch, a feature branch, or a release candidate branch. This is useful when testing unreleased tooling or contributing to open source projects.
# Install directly from the main branch for bleeding edge features
go install github.com/youruser/mytool/cmd/mytool@main
Commit hashes provide the strongest guarantee. They point to an immutable snapshot of the code. Use them when you need to debug a specific build or when a repository lacks proper semantic versioning.
# Lock to a specific commit hash to bypass tags entirely
go install github.com/youruser/mytool/cmd/mytool@a1b2c3d4e5f6
The module proxy caches these references. Once you install a specific commit, Go stores the source locally. Future installs of that exact commit skip the network entirely. This keeps your workflow fast even when you jump between branches.
Version suffixes are mandatory. The toolchain enforces them for a reason.
When things go sideways
Installation failures usually fall into three categories. Permission errors, missing modules, and environment misconfiguration.
Permission errors happen when Go cannot write to the $GOBIN directory. This occurs when $GOBIN points to a system directory like /usr/local/bin without elevated privileges. The compiler rejects the command with install: permission denied. Fix it by pointing $GOBIN to a directory inside your home folder, or by running the command with sudo if you absolutely must install to a system path. The community strongly prefers user-local directories. They avoid permission escalation and keep your system clean.
Missing modules occur when the repository does not exist, the path is misspelled, or the network cannot reach the module proxy. The toolchain reports module golang.org/x/tools/cmd/goimports: not found. Double check the import path. Verify your internet connection. If you are behind a corporate firewall, you may need to configure GOPROXY to point to an internal mirror.
Environment misconfiguration is the most common hurdle. Developers run go install, see no errors, and then type the tool name only to get command not found. The binary installed successfully. It just landed in a directory that is not in your PATH. Run go env GOBIN to find where it went. Add that directory to your shell configuration. Restart your terminal. The tool will appear.
Go also refuses to install packages that do not contain a main function. The command only produces executables. If you point it at a library package, you get package golang.org/x/tools/go/analysis is not a main package. Libraries are meant to be imported, not installed as standalone binaries.
Check your PATH before blaming the compiler. Most installation bugs are shell configuration problems.
When to reach for go install
Go provides several commands that touch the build process. Knowing which one to pick prevents friction.
Use go install when you want a standalone executable available system wide. Use go build when you want to compile a binary into your current directory for testing or distribution. Use go run when you want to execute code immediately without saving a compiled artifact. Use a language package manager like npm or pip when you are working in JavaScript or Python and need to manage third party libraries inside a project. Use go mod tidy when you need to sync your local go.mod file with the actual imports in your source code.
The toolchain separates concerns deliberately. go run is for experimentation. go build is for packaging. go install is for consumption. Pick the command that matches your intent.
Trust the separation. The toolchain rewards it.