go-list

List packages

$ go list ./...

$ go list std

$ go list -json time net/http

$ go list -m -u all

go list [-f format] [-json] [-m] [-u] [-deps] [-e] [-test] [build flags] [packages]

-f format
    Custom output format. Uses a Go template string to specify the desired output fields from a package or module struct.

-json
    JSON output. Prints a JSON object for each package or module found.

-m
    List modules. If specified, arguments are module patterns (or paths), and the command lists modules instead of packages.

-u
    Update network and module cache. Causes go list to check for newer versions of modules.

-deps
    List all transitive dependencies. Includes not just the specified packages but also all their dependencies.

-e
    Continue on errors. Does not stop on package loading errors, reporting them as warnings.

-test
    Include test packages. Considers `_test.go` files when determining package properties and dependencies.

[build flags]
    Standard Go build flags. Options like -tags, -mod, or -modfile that affect how packages are built and resolved.

[packages]
    Package patterns or module paths. Specifies which packages or modules to list. Examples: . (current), ./... (current and subdirectories), all (all known), github.com/foo/bar.

The go list command is a powerful utility within the Go toolchain used to display information about Go packages and modules. It can enumerate packages, their source directories, import paths, build context, and dependencies.

When run without arguments, it lists the current package. When given package patterns, it expands them to matching packages. A key feature is its ability to output data in various formats, including simple names, paths, or detailed structured JSON, making it indispensable for scripting and programmatic analysis of Go projects. It's often used to understand project structure, inspect module dependencies, or gather data for custom build systems and IDEs.

Performance can degrade for very large projects or when resolving extensive transitive dependencies, especially with network updates (-u).

The exact fields available for templating (-f) or JSON output depend on the Go version and whether packages or modules are being listed. Refer to Go documentation for the full struct definitions.

The -f flag allows for highly customizable output using Go template syntax. Common fields include .Dir (directory), .ImportPath (import path), .Deps (direct dependencies), .GoFiles (Go source files), and .Module.Path (module path). This enables extracting specific data points for automation and scripting.

By default, go list lists packages. Using the -m flag changes its behavior to list modules instead. When listing modules, the output fields available change to reflect module-specific properties like .Version, .Path, and .Main. Understanding this distinction is crucial for accurate querying of Go projects.

The go list command has been an integral part of the standard Go toolchain since its early versions, providing a foundational way to query information about Go source code. Its functionality significantly expanded with the introduction of Go modules in Go 1.11, adding the -m flag and module-specific fields to support the new dependency management system. This evolution made go list an essential tool for understanding and managing Go projects in the module era.

go build(1), go mod(1), go get(1), go run(1)