← All notes

Answer: A go.work file lists the module directories; commands in the workspace treat those modules as main modules, so local changes in one are used by the others.

Create one

mkdir ws && cd ws
go work init ./hello
go work use ./example/hello

Resulting go.work:

go 1.22
use (
    ./hello
    ./example/hello
)

Tips

• go.work can also contain replace directives that apply to the workspace.
• go work sync pushes workspace dependency versions back to each module.

Claims

• id: C1 claim: A go.work file specifies a workspace. source: S1 evidence: "In this step, we’ll create a go.work file to specify a workspace with the module."
• id: C2 claim: go work init creates a go.work file. source: S1 evidence: "The go work init command tells go to create a go.work file"
• id: C3 claim: A workspace is a collection of modules on disk. source: S2 evidence: "A workspace is a collection of modules on disk that are used as"
• id: C4 claim: Replace directives can appear in a workspace's go.work file. source: S2 evidence: "or a workspace’s go.work file. A replace directive may apply to a specific"

Sources

• [S1] Tutorial: Getting started with multi-module workspaces - The Go Programming Language. The Go Authors (go.dev). https://go.dev/doc/tutorial/workspaces . License: CC BY 4.0 (go.dev text). Accessed 2026-11-04.
• [S2] Go Modules Reference - The Go Programming Language. The Go Authors (go.dev). https://go.dev/ref/mod . License: CC BY 4.0 (go.dev text). Accessed 2026-11-04.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).

@misc{iil_note_j5tjakcv,
  author = {{iinventedlight}},
  title = {{Go multi-module workspaces (go.work)}},
  howpublished = {iinventedlight Library},
  year = {2026},
  date = {2026-11-04},
  url = {https://iinventedlight.com/library/notes/go-workspaces/},
  note = {Permanent ID iil:note:j5tjakcv. License: CC-BY-4.0.},
}

Markdown

Spotted a mistake? Use the MCP feedback tool or email hello@iinventedlight.com.

For language models and agents: start at /llms.txt. This page in Markdown: /library/notes/go-workspaces.md.