How to Use go list to Inspect Packages and Modules

Use go list to query package metadata, dependency versions, and build constraints directly from your terminal without compiling code. It is the primary tool for inspecting module graphs, finding specific files, and verifying which packages are included in a build.

To see all packages in your current module and their import paths, run go list ./.... This recursively lists every package under the current directory, which is useful for auditing your project structure or identifying unused code. If you need to filter by build tags or specific file patterns, you can add flags like -f to customize the output format.

Here is how to list all dependencies and their versions for a specific module:

# List all direct and indirect dependencies with versions
go list -m -json all | jq '.[0].Path, .[0].Version'

# Or a simpler, human-readable list of all modules
go list -m all

The -m flag tells go list to operate on modules rather than packages, while -json outputs structured data that can be piped to tools like jq for parsing. This is essential for generating dependency reports or checking for vulnerable versions in your supply chain.

You can also inspect specific package details, such as the files it contains or its build tags. For example, to see the source files of the net/http package:

# List source files for a specific package
go list -f '{{.GoFiles}}' net/http

# Show build tags required for a package
go list -f '{{.ImportPath}}: {{.Imports}}' ./cmd/myapp

The -f flag accepts Go template syntax, allowing you to extract specific fields like .GoFiles, .Imports, or .Deps. This is particularly helpful when you need to understand what a package imports or which files are compiled under different build tags.

For advanced use cases, you can check if a package is testable or inspect its test files:

# List test files associated with a package
go list -f '{{.TestGoFiles}} {{.XTestGoFiles}}' ./pkg/mypackage

Remember that go list respects your go.mod file and build constraints, so the output will reflect exactly what the Go toolchain sees during a build. If you encounter errors about missing modules, ensure you have run go mod tidy first to synchronize your module graph. This command is fast, reliable, and should be your first stop when debugging import paths or dependency issues.

The go list command is a tool that lets you see details about your Go code without running it. Think of it like a file inspector that tells you what packages exist, what files they contain, and what dependencies they need. You use it when you need to audit your project structure or debug why a specific file isn't being compiled.