Use go get to Manage Go Module Dependencies Safely

You will finish with a repeatable way to add, pin, upgrade or remove a dependency in a Go module, while seeing exactly what changed in go.mod and go.sum. This guide follows the module-aware behaviour of the installed Go command, which reports itself as Go 1.26.1. The local Debian package is golang-go 2:1.22~2build1.

Allow about fifteen minutes. You need an existing Go module, a working shell and permission to change that module's files. No command in this guide needs root. The examples use example.com/widget as a visible placeholder: replace it with a real module or package path before running it.

1. Confirm the module and command

Change into the module root, the directory containing go.mod. This is an ordinary read-only check:

$ cd /path/to/your/module
$ test -f go.mod && echo "module root: yes"
module root: yes
$ go version
go version go1.26.1 linux/amd64
$ go help get

The version output may differ on another machine. The key boundary is the go.mod file: go get updates requirements for the main module selected from the current directory, or from the current workspace. It is not a general package installer.

2. Add a dependency at the normal upgrade version

Ask for a package or module path. With no version suffix, go get resolves the request using its upgrade query, updates the selected requirement and downloads source into the module cache:

$ go get example.com/widget/parser
go: added example.com/widget v1.4.2

The exact version and messages depend on the module. A package path identifies the module that provides it. A module path can also be used when its root directory does not contain a buildable package. Inspect the resulting diff rather than assuming the command made only one small line change:

$ git diff -- go.mod go.sum
$ go list -m all | grep 'example.com/widget'

The second command should print the selected module and version. A module can bring other requirements with it, and Go's minimal version selection can raise versions that were already present.

3. Pin or downgrade a specific version

Put the version query immediately after the module or package path, separated by @. A semantic version makes the change easy to review and reproduce:

$ go get example.com/[email protected]
go: downgraded example.com/widget v1.4.2 => v1.3.0
$ go list -m example.com/widget
example.com/widget v1.3.0

A version is a minimum requirement in go.mod, not necessarily a promise that no other module can force a higher selected version. If the requested version conflicts with another explicit request, Go reports an error instead of choosing silently. Review go.mod and run the relevant tests after every intentional downgrade.

Do not paste an unreviewed branch name, revision or shell-expanded value into a dependency command. Go accepts version queries such as tags, branches, revisions, latest, patch and none, but each has different reproducibility and maintenance consequences. Prefer a released version for ordinary application work.

4. Upgrade dependencies deliberately

To update modules providing packages in the current module, use -u. The broader dependency graph may change, so save or commit a clean starting point first:

$ git status --short
$ go get -u ./...
$ git diff --stat
$ go test ./...

For patch-level dependency updates, use -u=patch, with the equals sign. -u patch is not the same command: patch would be treated as another argument. Use -t when test dependencies of the named packages should be considered as well:

$ go get -u=patch -t ./...
$ go test ./...

These commands change files. If tests fail, do not immediately run more update commands. Read the failure, inspect git diff, and either fix the compatibility issue or undo only this dependency change with a reviewed Git operation such as git restore --source=HEAD -- go.mod go.sum. That restore discards all uncommitted changes in those two files, so use it only when you have confirmed they contain no work you need.

5. Remove a dependency and check the fallout

To remove a module requirement, use the special @none query:

$ go get example.com/widget@none
go: removed example.com/widget v1.3.0
$ go test ./...

Go may downgrade other modules that no longer need their newer versions. The command does not remove imports from your source code, so tests or builds can fail if the package is still referenced. Remove or replace those imports, then run the command again if the module should no longer be required.

If your aim is simply to tidy requirements after source changes, use go mod tidy as a separate, reviewed operation. It considers packages and tests in the module and can add or remove requirements beyond the one you were investigating.

6. Do not use go get to install a command

Older Go workflows used go get to build and install executables. Module-aware Go no longer uses it for that job. To install a command at a version, use go install with the version suffix:

$ go install example.com/widget/cmd/[email protected]
$ command -v widget
/home/your-user/go/bin/widget

The executable location depends on GOBIN and GOPATH. A versioned go install ignores the current module's go.mod, which is useful for tools but means the tool is not recorded as an application dependency. Keep the version in your setup documentation or tool-management process.

7. Inspect the final state

Finish by checking the dependency graph, tests and file diff:

$ go list -m all > /tmp/module-list.txt
$ go test ./...
$ git diff --check
$ git diff -- go.mod go.sum
$ git status --short

git diff --check catches whitespace errors, while the final diff is where you verify that the selected versions, indirect requirements and checksums match the change you intended. The temporary module list is outside the repository and can be removed after inspection with rm /tmp/module-list.txt.