GO-LIST(1)

📦
version 1.27~1 · 4 versions
, in ubuntu stonking

👑 go-list 💅

okay bestie, welcome to the GO-LIST(1) page straight out of the Go programming tools and commands manual ✨ it's long so buckle up, this is part 1 and there's more coming, don't go anywhere 🎀

🌸 NAME 🌸

go-list — list packages or modules 🦋

✨ SYNOPSIS ✨

go list [-f format] [-json] [-m] [list flags] [build flags] [packages]

💖 DESCRIPTION 💖

List lists the named packages, one per line 💅 The most commonly-used flags are -f and -json, and they're the ones calling the shots on what the output actually looks like for each package. Every other list flag? Documented down below, they get into the more specific little details 👑

The default output just shows you the package import path, like so:

bytes
encoding/json
github.com/gorilla/mux
golang.org/x/net/html

simple, clean, iconic 🌈

🎀 OPTIONS 🎀

  • -f — specifies an alternate format for the list, using the syntax of package template 📝 The default output is equivalent to -f {{.ImportPath}}'`. The struct being passed to the template is this whole queen right here:
type Package struct {
    Dir            string   // directory containing package sources
    ImportPath     string   // import path of package in dir
    ImportComment  string   // path in import comment on package statement
    Name           string   // package name
    Doc            string   // package documentation string
    Target         string   // install path
    Shlib          string   // the shared library that contains this package (only set when -linkshared)
    Goroot         bool     // is this package in the Go root?
    Standard       bool     // is this package part of the standard Go library?
    Stale          bool     // would 'go install' do anything for this package?
    StaleReason    string   // explanation for Stale==true
    Root           string   // Go root or Go path dir containing this package
    ConflictDir    string   // this directory shadows Dir in $GOPATH
    BinaryOnly     bool     // binary-only package (no longer supported)
    ForTest        string   // package is only for use in named test
    Export         string   // file containing export data (when using -export)
    BuildID        string   // build ID of the compiled package (when using -export)
    Module         *Module  // info about package's containing module, if any (can be nil)
    Match          []string // command-line patterns matching this package
    DepOnly        bool     // package is only a dependency, not explicitly listed
    DefaultGODEBUG string  // default GODEBUG setting, for main packages

    // Source files
    GoFiles           []string   // .go source files (excluding CgoFiles, TestGoFiles, XTestGoFiles)
    CgoFiles          []string   // .go source files that import "C"
    CompiledGoFiles   []string   // .go files presented to compiler (when using -compiled)
    IgnoredGoFiles    []string   // .go source files ignored due to build constraints
    IgnoredOtherFiles []string // non-.go source files ignored due to build constraints
    CFiles            []string   // .c source files
    CXXFiles          []string   // .cc, .cxx and .cpp source files
    MFiles            []string   // .m source files
    HFiles            []string   // .h, .hh, .hpp and .hxx source files
    FFiles            []string   // .f, .F, .for and .f90 Fortran source files
    SFiles            []string   // .s source files
    SwigFiles         []string   // .swig files
    SwigCXXFiles      []string   // .swigcxx files
    SysoFiles         []string   // .syso object files to add to archive
    TestGoFiles       []string   // _test.go files in package
    XTestGoFiles      []string   // _test.go files outside package

    // Embedded files
    EmbedPatterns      []string // //go:embed patterns
    EmbedFiles         []string // files matched by EmbedPatterns
    TestEmbedPatterns  []string // //go:embed patterns in TestGoFiles
    TestEmbedFiles     []string // files matched by TestEmbedPatterns
    XTestEmbedPatterns []string // //go:embed patterns in XTestGoFiles
    XTestEmbedFiles    []string // files matched by XTestEmbedPatterns

    // Cgo directives
    CgoCFLAGS    []string // cgo: flags for C compiler
    CgoCPPFLAGS  []string // cgo: flags for C preprocessor
    CgoCXXFLAGS  []string // cgo: flags for C++ compiler
    CgoFFLAGS    []string // cgo: flags for Fortran compiler
    CgoLDFLAGS   []string // cgo: flags for linker
    CgoPkgConfig []string // cgo: pkg-config names

    // Dependency information
    Imports      []string          // import paths used by this package
    ImportMap    map[string]string // map from source import to ImportPath (identity entries omitted)
    Deps         []string          // all (recursively) imported dependencies
    TestImports  []string          // imports from TestGoFiles
    XTestImports []string          // imports from XTestGoFiles

    // Error information
    Incomplete bool            // this package or a dependency has an error
    Error      *PackageError   // error loading package
    DepsErrors []*PackageError // errors loading dependencies
}

Packages chillin' in vendor directories report an ImportPath that includes the path to the vendor directory (for example, d/vendor/p instead of p), and the whole reason is so that the ImportPath uniquely identifies a given copy of a package 🫶 The Imports, Deps, TestImports, and XTestImports lists also carry these expanded import paths. Wanna know more about vendoring? See golang.org/s/go15vendor 📚

The error information, if there is any, looks like this:

type PackageError struct {
    ImportStack   []string // shortest path from package named on command line to this one
    Pos           string   // position of error (if present, file:line:col)
    Err           string   // the error itself
}

The module information is a Module struct, defined in the discussion of list -m below 👇

The template function join calls strings.Join 💫

The template function context returns the build context, defined as:

type Context struct {
    GOARCH        string   // target architecture
    GOOS          string   // target operating system
    GOROOT        string   // Go root
    GOPATH        string   // Go path
    CgoEnabled    bool     // whether cgo can be used
    UseAllFiles   bool     // use files regardless of //go:build lines, file names
    Compiler      string   // compiler to assume when computing target paths
    BuildTags     []string // build constraints to match in //go:build lines
    ToolTags      []string // toolchain-specific build constraints
    ReleaseTags   []string // releases the current release is compatible with
    InstallSuffix string   // suffix to use in the name of the install dir
}

For more info about what all these fields actually mean, go read the documentation for the go/build package's Context type 📖

  • -json — causes the package data to be printed in JSON format instead of using the template format 🌈 ngl this one is so convenient. The JSON flag can optionally be provided with a set of comma-separated required field names to be output. If you do that, those required fields will always appear in the JSON output, but others may be omitted to save work in computing the JSON struct 💅
  • -compiled — causes list to set CompiledGoFiles to the Go source files presented to the compiler 🔥 Typically this means that it repeats the files listed in GoFiles and then also adds the Go code generated by processing CgoFiles and SwigFiles. The Imports list contains the union of all imports from both GoFiles and CompiledGoFiles 👑
  • -deps — causes list to iterate over not just the named packages but also all their dependencies 🦋 It visits them in a depth-first post-order traversal, so that a package is listed only after all its dependencies. Packages that weren't explicitly listed on the command line will have the DepOnly field set to true ✨
  • -e — changes the handling of erroneous packages, i.e. the ones that can't be found or are malformed 😭 By default, the list command prints an error to standard error for each erroneous package and omits the packages from consideration during the usual printing. With the -e flag, the list command never prints errors to standard error and instead processes the erroneous packages with the usual printing. Erroneous packages will have a non-empty ImportPath and a non-nil Error field; other information may or may not be missing (zeroed) 💀
  • -export — causes list to set the Export field to the name of a file containing up-to-date export information for the given package, and the BuildID field to the build ID of the compiled package 🎀
  • -find — causes list to identify the named packages but not resolve their dependencies: the Imports and Deps lists will be empty 🙈
⚠️ bestie listen — with the -find flag, the -deps, -test and -export commands cannot be used. periodt 💅
  • -test — causes list to report not only the named packages but also their test binaries (for packages with tests), to convey to source code analysis tools exactly how test binaries are constructed 🧚 The reported import path for a test binary is the import path of the package followed by a .test suffix, as in math/rand.test. When building a test, it is sometimes necessary to rebuild certain dependencies specially for that test (most commonly the tested package itself). The reported import path of a package recompiled for a particular test binary is followed by a space and the name of the test binary in brackets, as in math/rand [math/rand.test] or regexp [sort.test] 🎯 The ForTest field is also set to the name of the package being tested (math/rand or sort in the previous examples) 💖

The Dir, Target, Shlib, Root, ConflictDir, and Export file paths are all absolute paths 📍

By default, the lists GoFiles, CgoFiles, and so on hold names of files in Dir (that is, paths relative to Dir, not absolute paths). The generated files added when using the -compiled and -test flags are absolute paths referring to cached copies of generated Go source files 🌸 Although they are Go source files, the paths may not end in .go 👀

  • -m — causes list to list modules instead of packages 🦋

When listing modules, the -f flag still specifies a format template applied to a Go struct, but now a Module struct:

Oh and btw the struct that gets spit out with -json is literally this, character for character:

type Module struct {
    Path       string        // module path
    Query      string        // version query corresponding to this version
    Version    string        // module version
    Versions   []string      // available module versions
    Replace    *Module       // replaced by this module
    Time       *time.Time    // time version was created
    Update     *Module       // available update (with -u)
    Main       bool          // is this the main module?
    Indirect   bool          // module is only indirectly needed by main module
    Dir        string        // directory holding local copy of files, if any
    GoMod      string        // path to go.mod file describing module, if any
    GoVersion  string        // go version used in module
    Retracted  []string      // retraction information, if any (with -retracted or -u)
    Deprecated string        // deprecation message, if any (with -u)
    Error      *ModuleError  // error loading module
    Sum        string        // checksum for path, version (as in go.sum)
    GoModSum   string        // checksum for go.mod (as in go.sum)
    Origin     any           // provenance of module
    Reuse      bool          // reuse of old module info is safe
}

type ModuleError struct {
    Err string // the error itself
}

Okay so the file GoMod refers to may be outside the module directory if the module is sitting all cozy in the module cache, or if you busted out the -modfile flag. Just so you know bestie, it's not always where you'd expect 🫶

By default the output is the module path, then info about the version and the replacement if there is one. Like, go list -m all might print something like:

my/main/module
golang.org/x/text v0.3.0 => /tmp/text
rsc.io/pdf v0.1.1

The Module struct has a String method that formats exactly this line of output, which means the default format is equivalent to -f {{.String}}``. Cute right? The default IS a template 🎀

✨ Now here's a detail that genuinely matters: when a module has been replaced, its Replace field describes the replacement module, and its Dir field gets set to the replacement's source code, if that's present. (So like, if Replace is non-nil, then Dir is set to Replace.Dir, and you have no access to the replaced source code.) Not me being dramatic, that's just the actual behavior 💀

💅 the -u flag energy

The -u flag adds info about available upgrades. When the latest version of a given module is newer than the current one, list -u sets the Module's Update field to info about that newer module. And list -u will also set the Retracted field if the current version is retracted. The Module's String method shows an available upgrade by formatting the newer version in brackets after the current version. If a version is retracted, the string "(retracted)" follows it. So go list -m -u all might print:

my/main/module
golang.org/x/text v0.3.0 [v0.4.0] => /tmp/text
rsc.io/pdf v0.1.1 (retracted) [v0.1.2]

(And for the tool-builders out there: go list -m -u -json all may be way more convenient to parse. No cap ✨)

📚 -versions, -retracted, and the whole lore

The -versions flag makes list set the Module's Versions field to a list of all known versions of that module, ordered according to semantic versioning, earliest to latest. It also swaps the default output format so it shows the module path followed by the space-separated version list. Slay.

The -retracted flag makes list report info about retracted module versions. So when -retracted is used with -f or -json, the Retracted field explains why the version was retracted — and those strings are taken from the comments on the retract directive in the module's go.mod file. When -retracted is used with -versions, retracted versions get listed together with the unretracted versions. Fun fact: -retracted may be used with or without -m. Versatile icon 👑

🧚 modules, not packages (important distinction bestie)

The arguments to list -m are interpreted as a list of modules, NOT packages. Let that sink in.

  • The main module is the module containing the current directory.
  • The active modules are the main module and its dependencies.
  • With no arguments, list -m shows the main module.
  • With arguments, list -m shows the modules specified by those arguments.
  • Any of the active modules can be specified by its module path.
  • The special pattern "all" specifies all the active modules — first the main module, and then dependencies sorted by module path.
  • A pattern containing "..." specifies the active modules whose module paths match the pattern.
  • A query of the form path@version specifies the result of that query, which is not limited to active modules.

And if you want the full lore on module queries, run go help modules. Iykyk 🌸

🪄 the module template function

The template function "module" takes a single string argument that has to be either a module path or a query, and it returns the specified module as a Module struct. And if something goes sideways? The result will be a Module struct with a non-nil Error field. So check that field, bestie, don't just assume 🙈

♻️ -reuse=old.json explained

When you're using -m, the -reuse=old.json flag accepts the name of a file containing the JSON output of a previous go list -m -json invocation — and it has to be with the same set of modifier flags (like -u, -retracted, and -versions). The go command may use this file to figure out that a module is unchanged since the previous invocation and avoid redownloading info about it. Modules that don't get redownloaded will be marked in the new output by setting the Reuse field to true. Normally the module cache gives you this kind of reuse automatically, so the -reuse flag is useful on systems that do not preserve the module cache. Situational icon 💅

🔗 go read these too

  • For more about build flags, run go help build.
  • For more about specifying packages, run go help packages.
  • For more about modules, the docs live at https://go.dev/ref/mod.

👑 AUTHOR 👑

This manual page was created using help2man and afterwards updating the output (yes, the pipeline was: generate, then hand-edit, iconic honestly). It is maintained by the Debian Go Compiler Team <team+go-compiler@tracker.debian.org> for the Debian project — and may be used by others too, they're generous like that 🫶

And that's the whole page bestie, we made it to the end 🎀 This one is from Go 1.27 and it's dated August 2026. Go forth and go list -m responsibly, mwah 💖🦋✨

📦 where this page comes from