How to Use Go Multi-Module Workspaces (Go 1.22+)

In this tutorial, you'll learn about How to Use Go Multi. We cover key concepts, practical examples, and best practices.

The Problem

You are developing two Go modules side by side — a library (github.com/you/lib) and a service (github.com/you/service) that depends on the library. Without workspaces, you must either publish the library after every change or add replace directives in go.mod. Both approaches are error-prone, clutter the module file, and make it easy to accidentally push a replace directive to production.

Quick Fix

1. Initialize a workspace from the root directory

go work init ./service ./lib

Expected output:

# (no output — creates go.work)

The generated go.work file:

go 1.22

use (
    ./service
    ./lib
)

2. Add more modules to an existing workspace

go work use ./another-module

3. Build and test using local module paths

cd service
go build ./...

Expected output:

# (no errors — lib resolved from local ./lib)

The workspace overrides the module resolution so that service uses the local copy of lib regardless of what go.mod says.

4. Override a specific version with local code

// go.work
go 1.22

use ./service

replace example.com/lib v1.2.3 => ./lib

This is useful when service/go.mod pins lib at v1.2.3 but you want to develop against an unreleased v1.3.0.

5. Verify the workspace is active

go env GOWORK

Expected output:

/home/user/projects/myapp/go.work

If GOWORK is empty, the workspace is not active. Run go work use from the correct directory.

6. Sync and tidy all modules

go work sync
go mod tidy

Expected output:

# (no output — all go.mod files synced)

7. Keep go.work out of CI

# Add to .gitignore if you don't want to share workspace config
echo 'go.work' >> .gitignore
echo 'go.work.sum' >> .gitignore

# Or commit go.work.example for reference
cp go.work go.work.example

In CI, build without the workspace:

GOWORK=off go build -mod=mod ./...

8. Debug workspace resolution issues

go work use ./missing-module

If the module path does not exist, you get:

go: directory ./missing-module does not contain a go.mod file

Verify each workspace directory has a valid go.mod:

ls */go.mod

9. Add go.work.sum to version control

git add go.work.sum

The checksum file ensures reproducible builds when using workspaces. Without it, different machines may resolve different versions.

Prevention

• Keep go.work out of the CI pipeline — commit only go.work.example for documentation purposes
• Run go work sync after adding or removing dependencies to keep all go.mod files consistent
• Run go mod tidy in each workspace module before committing changes
• Document the workspace layout in your project README so new contributors know how to activate it
• Use go env GOWORK in shell prompts to remind yourself when a workspace is active