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] [build flags] [packages...]

-f format
    Custom output format using Go template syntax (e.g., '{{.ImportPath}}').

-json
    Emit JSON instead of default format for structured output.

-m
    List modules (paths, versions, replacements) instead of packages.

-a
    Include all packages, even those previously compiled.

-e
    Report all packages, including those with errors.

-test
    Include external test packages in listing.

-u
    List packages with available newer versions.

-tags tag,list
    Build constraints to consider during listing.

-trimpath
    Omit install suffixes from source paths.

go list is a powerful command in the Go toolchain used to query and list information about Go packages or modules. It outputs details such as import paths, directories, source files, dependencies, and metadata based on patterns or explicit package names provided.

By default, running go list without arguments lists packages in the current directory. It supports wildcard patterns like ./... for recursive listing or cmd/... for subdirectories. The command integrates seamlessly with Go modules (since Go 1.11) and legacy GOPATH workspaces.

Key features include custom templating with -f to extract specific fields (e.g., '{{.Deps}}' for dependencies), JSON output for machine-readable data via -json, and module listing with -m. Build flags allow filtering, such as -u to highlight upgradable packages or -test to include test variants.

It's essential for scripting, CI/CD pipelines, IDEs, and tools like go mod graph or dependency analyzers. Output variables include ImportPath, Dir, GoFiles, Deps, Module, and more—detailed in go help list. Usage requires Go installed and a valid workspace.

Behavior varies between GOPATH and module modes. Output fields depend on Go version—use go doc cmd/go/internal/list for details. Does not download modules; run go mod download first if needed. Build flags may alter results unexpectedly.

-f '{{.ImportPath}} {{.Deps}}' lists paths and deps.
-f '{{.Name}}: {{join .GoFiles "\n"}}' shows package name and files.
See go help list for full variables.

Supports ./... (workspace), example.com/pkg (module), all (std+workspace), cmd/... (subtree).

Introduced in Go 1.0 (March 2012) for basic package listing in GOPATH. Enhanced in Go 1.4 with template support. Module listing (-m) and JSON output added in Go 1.11 (2018) with modules. Continuously improved for dependency queries and vendoring support in later releases.

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