Workspaces and replace directives

A workspace is a go.work file at the top of a tree that lists several modules and makes them build together. It exists for the day a program and its library change in the same commit: without a workspace the program depends on a published version of the library, and the change would need a tag, a push and a version bump before it could be tested. The versions lesson explained where a requirement comes from; a workspace replaces the requirement with a local directory.

Two modules that cannot see each other

The app imports example.com/lib, which is not published and not on the proxy. The requirement line names version v0.0.0 as a placeholder, so a build without the workspace asks the proxy for a module that does not exist. That failure is the starting point, and the workspace is the fix.

go run ./app

main module (example.com/root) does not contain package example.com/root/app

The error names the module and the reason: the proxy has no such module. Note that the same tree with a replace directive would also work, and the next sections compare the two solutions.

go work init

go work init ./app ./lib writes a go.work file that uses both directories. From then on the build resolves example.com/lib to the local directory, and no version of it is fetched. The file is meant to be read: one use line per module, plus a Go version.

go work init ./app ./lib && cat go.work

go 1.26.10

use (
./app
./lib
)

go run ./app

hello, workspace

The program ran against the local library with no version and no publish step. go work use ./third adds another directory later, and go work sync pushes the workspace's selected versions back into the go.mod files, which is the maintenance command for a workspace that is kept.

replace in go.mod

The older way to point a module at a local directory is a replace line in go.mod: replace example.com/lib => ../lib. It applies to that one module and travels with it, so a program that is built from the repository always uses the local copy, which is wrong for a published library and right for a fork that must not be published. A workspace is the better tool for local development because it does not modify the module files.

The rule of thumb: commit go.work in an application repository where the whole team builds the same modules, and do not commit it in a library meant to be used alone. A go.work that names an absolute path or a colleague's checkout breaks everyone else's build, which is the reason some teams ignore it and keep the replace form for the cases that need it.

Exercises

  1. Add a third module to the workspace and call it from the app. What happens to the go.work file?
  2. Try the same tree with a replace line instead of a workspace. Which files change, and what would a published library do with that line?
  3. Remove the workspace and run go build ./.... Which error comes first, and why does the module path matter?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does a go.work file do?

    Answer

    Lists modules that build together from a shared root

    Each module keeps its go.mod; the workspace adds local resolution on top.

  2. Which command creates a workspace?

    Answer

    go work init ./app ./lib

    It writes go.work with one use line per directory.

  3. What does a replace directive in go.mod do?

    Answer

    Points a module path at another version or directory

    It affects that module only and is part of its go.mod.

  4. Why is a workspace preferred over replace for local development?

    Answer

    It leaves the module files unchanged

    The change is in go.work, which is not part of any published module.

  5. What does go work use do?

    Answer

    Adds or updates a module directory in go.work

    It edits the use list of an existing workspace.

  6. When should go.work not be committed?

    Answer

    In a library that is meant to build on its own

    A workspace that assumes a sibling checkout breaks a standalone build.

  7. What does a build do when the workspace lists the module?

    Answer

    Resolves the import to the local directory and fetches nothing

    Local resolution takes precedence over the requirement.

  8. What does go work sync do?

    Answer

    Writes the workspace's selected versions back into the modules' go.mod files

    It is the maintenance command for a workspace that is kept.

  9. What must each module in a workspace still have?

    Answer

    Its own go.mod

    The workspace does not replace the module files; it composes them.

  10. What is the danger of an absolute path in go.work?

    Answer

    It only works on one machine

    A colleague's checkout path is not a portable build input.

The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev