Black Lives Matter. Support the Equal Justice Initiative.

Managing dependencies

When your code uses external packages, those packages (distributed as modules) become dependencies. Over time, you may need to upgrade them or replace them. Go provides dependency management tools that help you keep your Go applications secure as you incorporate external dependencies.

This topic describes how to perform tasks to manage dependencies you take on in your code. You can perform most of these with Go tools. This topic also describes how to perform a few other dependency-related tasks you might find useful.

See also

Workflow for using and managing dependencies

You can get and use useful packages with Go tools. On pkg.go.dev, you can search for packages you might find useful, then use the go command to import those packages into your own code to call their functions.

The following lists the most common dependency management steps. For more about each, see the sections in this topic.

  1. Locate useful packages on pkg.go.dev.
  2. Import the packages you want in your code.
  3. Add your code to a module for dependency tracking (if it isn’t in a module already). See Enabling dependency tracking
  4. Add external packages as dependencies so you can manage them.
  5. Upgrade or downgrade dependency versions as needed over time.

Managing dependencies as modules

In Go, you manage dependencies as modules that contain the packages you import. This process is supported by:

Locating and importing useful packages

You can search pkg.go.dev to find packages with functions you might find useful.

When you’ve found a package you want to use in your code, locate the package path at the top of the page and click the Copy path button to copy the path to your clipboard. In your own code, paste the path into an import statement, as in the following example:

import "rsc.io/quote"

After your code imports the package, enable dependency tracking and get the package’s code to compile with. For more, see Enabling dependency tracking in your code and Adding a dependency.

Enabling dependency tracking in your code

To track and manage the dependencies you add, you begin by putting your code in its own module. This creates a go.mod file at the root of your source tree. Dependencies you add will be listed in that file.

To add your code to its own module, use the go mod init command. For example, from the command line, change to your code’s root directory, then run the command as in the following example:

$ go mod init example/mymodule

The go mod init command’s argument is your module’s module path. If possible, the module path should be the repository location of your source code.

If at first you don’t know the module’s eventual repository location, use a safe substitute. This might be the name of a domain you own or another name you control (such as your company name), along with a path following from the module’s name or source directory. For more, see Naming a module.

As you use Go tools to manage dependencies, the tools update the go.mod file so that it maintains a current list of your dependencies.

When you add dependencies, Go tools also create a go.sum file that contains checksums of modules you depend on. Go uses this to verify the integrity of downloaded module files, especially for other developers working on your project.

Include the go.mod and go.sum files in your repository with your code.

See the go.mod reference for more.

Naming a module

When you run go mod init to create a module for tracking dependencies, you specify a module path that serves as the module’s name. The module path becomes the import path prefix for packages in the module. Be sure to specify a module path that won’t conflict with the module path of other modules.

At a minimum, a module path need only indicate something about its origin, such as a company or author or owner name. But the path might also be more descriptive about what the module is or does.

The module path is typically of the following form:

<prefix>/<descriptive-text>

Reserved module path prefixes

Go guarantees that the following strings won’t be used in package names.

Adding a dependency

Once you’re importing packages from a published module, you can add that module to manage as a dependency by using the go get command.

The command does the following:

The following describes a few examples.

The command also authenticates each module it downloads. This ensures that it’s unchanged from when the module was published. If the module has changed since it was published – for example, the developer changed the contents of the commit – Go tools will present a security error. This authentication check protects you from modules that might have been tampered with.

Getting a specific dependency version

You can get a specific version of a dependency module by specifying its version in the go get command. The command updates the require directive in your go.mod file (though you can also update that manually).

You might want to do this if:

Here are examples for using the go get command:

The following go.mod file require directive example (see the [go.mod reference]/doc/modules/gomod-ref) for more) illustrates how to require a specific version number:

require example.com/theirmodule v1.3.4

Discovering available updates

You can check to see if there are newer versions of dependencies you’re already using in your current module. Use the go list command to display a list of your module’s dependencies, along with the latest version available for that module. Once you’ve discovered available upgrades, you can try them out with your code to decide whether or not to upgrade to new versions.

For more about the go list command, see go list -m.

Here are a couple of examples.

Upgrading or downgrading a dependency

You can upgrade or downgrade a dependency module by using Go tools to discover available versions, then add a different version as a dependency.

  1. To discover new versions use the go list command as described in Discovering available updates.

  2. To add a particular version as a dependency, use the go get command as described in Getting a specific dependency version.

Synchronizing your code’s dependencies

You can ensure that you’re managing dependencies for all of your code’s imported packages while also removing dependencies for packages you’re no longer importing.

This can be useful when you’ve been making changes to your code and dependencies, possibly creating a collection of managed dependencies and downloaded modules that no longer match the collection specifically required by the packages imported in your code.

To keep your managed dependency set tidy, use the go mod tidy command. Using the set of packages imported in your code, this command edits your go.mod file to add modules that are necessary but missing. It also removes unused modules that don’t provide any relevant packages.

The command has no arguments except for one flag, -v, that prints information about removed modules.

$ go mod tidy

Developing and testing against unpublished module code

You can specify that your code should use dependency modules that may not be published. The code for these modules might be in their respective repositories, in a fork of those repositories, or on a drive with the current module that consumes them.

You might want to do this when:

Requiring module code in a local directory

You can specify that the code for a required module is on the same local drive as the code that requires it. You might find this useful when you are:

To tell Go commands to use the local copy of the module’s code, use the replace directive in your go.mod file to replace the module path given in a require directive. See the go.mod reference for more about directives.

In the following go.mod file example, the current module requires the external module example.com/theirmodule, with a nonexistent version number (v0.0.0-unpublished) used to ensure the replacement works correctly. The replace directive then replaces the original module path with ../theirmodule, a directory that is at the same level as the current module’s directory.

module example.com/mymodule

go 1.16

require example.com/theirmodule v0.0.0-unpublished

replace example.com/theirmodule v0.0.0-unpublished => ../theirmodule

When setting up a require/replace pair, use the go mod edit and go get commands to ensure that requirements described by the file remain consistent:

$ go mod edit -replace=example.com/[email protected]=../theirmodule
$ go get -d example.com/[email protected]

Note: When you use the replace directive, Go tools don’t authenticate external modules as described in Adding a dependency.

For more about version numbers, see Module version numbering.

Requiring external module code from your own repository fork

When you have forked an external module’s repository (such as to fix an issue in the module’s code or to add a feature), you can have Go tools use your fork for the module’s source. This can be useful for testing changes from your own code. (Note that you can also require the module code in a directory that’s on the local drive with the module that requires it. For more, see Requiring module code in a local directory.)

You do this by using a replace directive in your go.mod file to replace the external module’s original module path with a path to the fork in your repository. This directs Go tools to use the replacement path (the fork’s location) when compiling, for example, while allowing you to leave import statements unchanged from the original module path.

For more about the replace directive, see the go.mod file reference.

In the following go.mod file example, the current module requires the external module example.com/theirmodule. The replace directive then replaces the original module path with example.com/myfork/theirmodule, a fork of the module’s own repository.

module example.com/mymodule

go 1.16

require example.com/theirmodule v1.2.3

replace example.com/theirmodule v1.2.3 => example.com/myfork/theirmodule v1.2.3-fixed

When setting up a require/replace pair, use Go tool commands to ensure that requirements described by the file remain consistent. Use the go list command to get the version in use by the current module. Then use the go mod edit command to replace the required module with the fork:

$ go list -m example.com/theirmodule
example.com/theirmodule v1.2.3
$ go mod edit -replace=example.com/[email protected]=example.com/myfork/[email protected]

Note: When you use the replace directive, Go tools don’t authenticate external modules as described in Adding a dependency.

For more about version numbers, see Module version numbering.

Getting a specific commit using a repository identifier

You can use the go get command to add unpublished code for a module from a specific commit in its repository.

To do this, you use the go get command, specifying the code you want with an @ sign. When you use go get, the command will add to your go.mod file a require directive that requires the external module, using a pseudo-version number based on details about the commit.

The following examples provide a few illustrations. These are based on a module whose source is in a git repository.

Removing a dependency

When your code no longer uses any packages in a module, you can stop tracking the module as a dependency.

To stop tracking all unused modules, run the go mod tidy command. This command may also add missing dependencies needed to build packages in your module.

$ go mod tidy

To remove a specific dependency, use the go get command, specifying the module’s module path and appending @none, as in the following example:

$ go get example.com/[email protected]

The go get command will also downgrade or remove other dependencies that depend on the removed module.

Specifying a module proxy server

When you use Go tools to work with modules, the tools by default download modules from proxy.golang.org (a public Google-run module mirror) or directly from the module’s repository. You can specify that Go tools should instead use another proxy server for downloading and authenticating modules.

You might want to do this if you (or your team) have set up or chosen a different module proxy server that you want to use. For example, some set up a module proxy server in order to have greater control over how dependencies are used.

To specify another module proxy server for Go tools use, set the GOPROXY environment variable to the URL of one or more servers. Go tools will try each URL in the order you specify. By default, GOPROXY specifies a public Google-run module proxy first, then direct download from the module’s repository (as specified in its module path):

GOPROXY="https://proxy.golang.org,direct"

For more about the GOPROXY environment variable, including values to support other behavior, see the go command reference.

You can set the variable to URLs for other module proxy servers, separating URLs with either a comma or a pipe.