Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท The go Command and Tools

The go work command

Reference for the go work command and go.work files: work on several modules at once, init, use, edit, sync and vendor, the GOWORK variable and common mistakes.

A workspace lets the go command treat several modules on your disk as one build. Normally each module is built on its own and its dependencies come from the versions in its go.mod. When you are changing a library and an application that uses it at the same time, a workspace makes the application see your local copy of the library without editing any go.mod. Workspaces were added in Go 1.18.

A workspace is described by a go.work file. The go work command creates and edits that file. Once the file exists, ordinary commands such as go build, go test and go run pick it up automatically, searching the current directory and its parents the same way they look for go.mod.

Terminal
go work init ./api ./shared   # create go.work listing two modules
go work use ./tools/cli       # add another module directory
go work sync                  # push the workspace's versions back into each go.mod

Try it

A workspace cannot be created inside the site's single-file sandbox, so these two programs are small stand-ins written with the standard library. They parse the same kind of text a go.work file contains and apply two of the real rules.

Go Reading a go.work file (stand-in parser)

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 go line must cover every module

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 work init [moddirs]
go work use [-r] [moddirs]
go work edit [editing flags] [go.work]
go work sync
go work vendor [-e] [-v] [-o outdir]
Subcommand Description
init [moddirs] Creates go.work in the current directory with a use line for each directory given. With no arguments the file starts empty.
use [-r] [moddirs] Adds directories to the use list. A directory that no longer exists is removed from the list. With -r each argument is searched recursively for modules.
edit Changes the file from scripts: -use=dir, -dropuse=dir, -replace=old[@v]=new[@v], -dropreplace, -go=version, -toolchain=name, -godebug, -fmt, -print and -json.
sync Computes the workspace's build list and writes the chosen dependency versions back to each workspace module's go.mod.
vendor Copies all dependencies of the workspace's modules into a vendor directory at the workspace root (Go 1.22).

The go.work file has these directives: go (language version, at least as high as every module's), toolchain, godebug, use (a module directory, relative to the file), and replace (same syntax as in go.mod; applies to the whole workspace and takes priority over a replace inside a module).

Environment and flags: GOWORK names the file to use. GOWORK=off (or the build flag -workfile=off) turns workspace mode off. go env GOWORK shows which file is active, and is empty when there is none.

Errors and edge cases:

  • Two workspace modules with the same module path are an error.
  • If the go line in go.work is lower than a module's, the go command asks you to raise it.
  • A use directory without a go.mod file is an error.

Usage notes

  • Version selection is merged. All workspace modules are treated as main modules, and each dependency gets the highest version required by any of them (minimal version selection over the union).
  • Do not commit go.work for a published library. It describes your machine's layout. Teams that share a monorepo often commit it on purpose, so the rule is: commit it only when everyone should build the same set of modules.
  • go.work.sum holds checksums that are not recorded in any module's go.sum. It sits next to go.work.
  • Module commands ignore the workspace. go mod tidy and go mod verify work on one module and do not read go.work; use go work sync for the workspace.
  • Packages from outside modules fail. Imports resolve only through workspace modules or the dependencies they require.
  • Debugging "why this version?" go list -m all inside a workspace lists the merged build list. Run with GOWORK=off to see what CI, which has no go.work, will build.
  • Vendoring (go work vendor) makes -mod=vendor the default when vendor/modules.txt exists and the go line is 1.22 or higher.