Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท The go Command and Tools

The go list command

Reference for go list: print packages and modules, choose fields with -f templates, JSON output, -deps, -m, -u, -test and patterns like ./... and std.

go list prints information about packages (or, with -m, modules). By default it prints one import path per line, which makes it the standard way to expand a pattern such as ./... into a list of packages for scripts. With -f you pick exactly the fields you want using a Go template, and with -json you get everything as JSON.

Behind many other tools is the same data: which files belong to a package, what it imports, which build tags select it, and which module owns it. If you ever need to answer "what does this build actually include?", go list is the first tool to try.

Terminal
go list ./...                              # all packages in this module
go list -f '{{.ImportPath}}: {{.Imports}}' .
go list -m all                             # every module in the build
go list -deps -f '{{if not .Standard}}{{.ImportPath}}{{end}}' .

Try it

The data go list prints comes from the go/build package, and -f uses text/template. The examples use both: first to read a real standard-library package, then to format a list the way -f does.

Go Package information from go/build

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go The -f flag is a text/template

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Terminal
go list [-f format] [-json[=fields]] [flags] [packages]
go list -m [-f format] [-u] [-versions] [modules]
Flag Description
-f format Print each package using a text/template with the Package struct as data (or Module with -m).
-json One JSON object per package. -json=ImportPath,Dir limits the fields.
-deps Include all dependencies, not just the named packages, in dependency order.
-test Also list the test packages and generated test main packages.
-find Do not resolve imports, which makes it fast. Good for expanding patterns.
-e Report errors inside the output instead of failing.
-export Include the compiled export file path (Export field).
-compiled Include generated Go files and cgo output in CompiledGoFiles.
-m List modules instead of packages. all means every module in the build; -m alone prints the main module.
-u With -m, show available upgrades.
-versions With -m, list all known versions of a module.
-retracted Include retracted versions in -versions.

Useful Package fields

Field Meaning
Dir, ImportPath, Name, Doc Where it is, its import path, package name, first sentence of the doc comment.
Standard, Module Whether it is in the standard library; the owning module (Path, Version, Dir, GoMod).
GoFiles, CgoFiles, IgnoredGoFiles, TestGoFiles, XTestGoFiles Source files selected (and excluded) by the current build constraints.
Imports, Deps, TestImports Direct imports, all transitive dependencies, imports from tests.
Stale, StaleReason Whether a rebuild is needed (best-effort).
Error, DepsErrors Problems found while loading.

Patterns: . (current), ./... (current and below), std (standard library), all (everything for the main module), cmd (toolchain commands), or import paths with ... wildcards such as example.com/shop/....

Usage notes

  • List all packages: go list ./... skips vendor/ and any directory that begins with _ or ., or is called testdata.
  • The -f template has helpers. Besides the standard text/template functions, join joins strings: {{join .Imports ", "}}. Whitespace between actions is kept, so wrap lines with {{"\n"}} when needed.
  • Combine with shell. go test $(go list ./... | grep -v /integration) runs a subset of packages. In scripts, prefer -f '{{.Dir}}' to find folders.
  • Find outdated dependencies: go list -m -u all marks modules that have newer versions in brackets. See go get to upgrade.
  • Which packages does my binary use? go list -deps -f '{{if not .Standard}}{{.ImportPath}}{{end}}' . shows only third-party and your own packages.
  • Constraints decide files. GoFiles lists the files for your current GOOS, GOARCH and tags; files that did not match appear in IgnoredGoFiles. Run with GOOS=windows go list ... to see another target.
  • It may download. Listing packages from modules not yet in the cache triggers downloads, unless you use -mod=readonly (the default) and everything is already recorded.
  • Edge cases. A pattern that matches nothing prints a warning and exits with status 1. Use -e for tolerant output when you are scripting over a broken tree.
  • go list -m -json is the machine-readable view of go.mod, including replace targets and indirect flags; see go mod.