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
- Add a third module to the workspace and call it from the app. What happens to the go.work file?
- 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?
- 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.
-
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.
-
Which command creates a workspace?
Answer
go work init ./app ./lib
It writes go.work with one use line per directory.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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