go.work — workspace mode

1. Introduction

When you write an application, it rarely lives in a vacuum. Almost always there’s at least one library you’re developing alongside it: a shared utilities package, a separate domain-logic module, an internal SDK, or simply “moved it nicely into a separate repository.” And that’s when programmers’ favorite game begins: “why doesn’t my application see changes in the library even though I literally just wrote them?”

Before workspace mode, the typical path looked like this: either you publish changes to the library (often too early and inconvenient), or you temporarily add a replace to a local folder in the application’s go.mod, and then remember to remove it before publishing. And “remember” is, as we know, an optimistic scenario.

Workspace mode solves exactly this pain: Go lets you work with multiple modules at the same time without forcing you to constantly edit each module’s go.mod just for local development. The idea is stated very plainly: workspaces let you work with multiple modules simultaneously without having to modify go.mod for each module, while each module inside the workspace is treated as “main” when resolving dependencies.

2. What workspace mode is: a mental model

It’s important to pause for a minute and agree on a mental model; otherwise, go.work will feel like yet another mysterious file that you “need to create somewhere so it works.” That’s not how we do it: we’re not shamans, we’re engineers… or at least we try to look like engineers in the computer’s eyes.

Workspace is a Go tooling mode in which tools consider not one “main module,” but a set of local modules listed in go.work. As a result, when one module imports packages from another module, Go can take their sources directly from disk rather than from a “downloaded dependency version.”

From the go tool’s perspective, it boils down to this: it reads go.work and gets three things—Go version, a list of module directories, and a list of replacements. This is a useful anchor: go.work does not “affect Go syntax,” it affects how tools resolve dependencies.

Let’s draw a simple diagram:

flowchart TD
    A[You run: go test / go run / go build] --> B[Go looks for context]
    B --> C{Is workspace mode enabled?}
    C -->|no| D[Work as usual: one main module via go.mod]
    C -->|yes| E[Read go.work]
    E --> F[use: list of modules on disk]
    F --> G[Imports between these modules come from local sources]

3. The go.work file: how to read it

The go.work file is intentionally made to look like go.mod, so your brain doesn’t overheat. It has directives, and the most important one for us is use.

go.work contains the go, use, and (if needed) replace directives. In this lecture, the key is understanding use: it adds an on-disk module to the workspace (that is, a directory that contains a go.mod file).

An example of a minimal go.work for Go 1.25:

// go.work
go 1.25

use (
    ./todoapp
    ./todolib
)

There are no imports or “package paths” here—only module directories. And that’s logical: a module is defined by the go.mod file, and go.work simply says, “treat these modules as local and work with them together.”

4. Example: todoapp + todolib in one workspace

Let’s continue our learning storyline with a task app (a hypothetical todoapp). Imagine that at some point you decided to move the task model and utilities into a separate module todolib, because “it looks nicer” (and because you’re a future library author, not just someone who writes main.go for the rest of your life).

Let’s make this structure:

workspace/
  go.work
  todoapp/
    go.mod
    main.go
  todolib/
    go.mod
    task/
      task.go

todolib/go.mod: the library module

// todolib/go.mod
module example.com/todolib

go 1.25

The task package inside todolib

Let’s say we have a super-modest function to normalize a task title. Nothing heroic—just clear and realistic.

package task

import "strings"

func NormalizeTitle(s string) string {
	return strings.TrimSpace(s)
}

todoapp/go.mod: the application module

// todoapp/go.mod
module example.com/todoapp

go 1.25

require example.com/todolib v0.0.0

The v0.0.0 version here is just a placeholder for the example (in real life, you’d pick a specific version or work differently). Right now, the important idea is: the application depends on the library module.

Import the library in todoapp/main.go

package main

import (
	"fmt"

	"example.com/todolib/task"
)

func main() {
	title := task.NormalizeTitle("   buy milk   ")
	fmt.Println(title) // buy milk
}

If you run todoapp without a workspace, Go will try to find the dependency example.com/todolib as a module (download it or take it from cache, depending on your environment). But if you have a go.work file and it says use ./todolib, then Go will take example.com/todolib from the local folder.

And this is where the good part happens: you change NormalizeTitle in todolib, immediately run todoapp—and the app sees the changes right away, without the dance of adding replace to go.mod.

5. Creating and extending a workspace

When you first encounter workspaces, a practical question comes up: “Okay, but how do I actually set this up?” You can create go.work by hand, or you can ask Go tools to do it for you.

The basic path is: a workspace is created with go work init (optionally with a list of module directories), and you can add modules via go work use [moddir] or by editing the file manually. An important detail: the workspace does not have to physically contain the modules you’re working with. That is, go.work is a “map,” not a “container.”

If you have a monorepo, it’s convenient to live like this:

repo/
  go.work
  services/
    todoapp/     (go.mod)
    importtool/  (go.mod)
  libs/
    todolib/     (go.mod)
    textkit/     (go.mod)

And if you have several repositories next to each other on disk, you can create a “workspace directory” that contains only go.work, while the modules live in neighboring directories. This is especially nice when you want to fix a bug in a library and immediately verify it in the app, without turning one repository into the other’s dumping ground.

Another practical feature is recursive module adding. There’s a go work use -r . option that recursively adds directories containing go.mod. This is handy if you have many modules in a directory tree and don’t want to list them by hand.

6. Diagnosing and maintaining a workspace

How to tell whether workspace mode is enabled

A very typical situation: “it worked yesterday,” but today the IDE highlights imports in red, or go test suddenly pulls not the local library but some version from the network or cache. In moments like that, you want to blame the universe, retrograde Mercury, and the neighbor on Wi‑Fi. But it’s better to start simple: make sure you’re actually in workspace mode.

Go tools rely on the GOWORK environment variable: if it points to a file ending with .work, workspace mode is enabled. To see which go.work is being used, run go env GOWORK: if the output is empty, workspace mode is not active.

Why is this especially important for beginners? Because workspaces are not a “part of the code,” they are a “run context.” And run context is the easiest thing to break: you ran a command from the wrong folder, opened the wrong root in the IDE, the terminal points at a different project—and now you’re debugging a different reality than you think.

go work sync: when you need it

The go work sync command sounds like it should fix life, relationships, and dependencies. In practice, it does something more specific: it “pushes dependencies from go.work back into the go.mod files of the workspace modules.”

When might this be needed? Imagine you added a new import of an external package in one module, Go pulled in the dependency, but another workspace module now needs a consistent state. Sometimes tools, IDEs, or checks want the modules’ go.mod to be brought to the expected shape. That’s when sync helps align everything.

But it’s important not to treat sync as “pressed it—and now I don’t have to understand anything.” Any command that changes go.mod deserves respect. In short: go work sync is useful when you consciously manage multiple modules and want their go.mod files to reflect the workspace state rather than each living its own life.

7. Multi-module development scenarios with go.work

When you first hear “multiple modules at once,” it can sound like something for big corporations where each microservice has its own module, each microservice has its own team, and each team has its own chat where they discuss who broke the build. In reality, go.work is useful in small projects too; the scenarios are just simpler.

“I edit a library and immediately test it in the app”

This is the most common scenario. You make a change in todolib and then run todoapp. In workspace mode, the application uses the local sources of todolib instead of the published version. That’s exactly why workspaces exist: you can work with multiple modules at once without having to use replace in go.mod and then remembering not to forget to remove it.

A monorepo with multiple modules

If you have a monorepo, go.work becomes a “build point” for local development. You can keep multiple modules, while still having a single space where the IDE can jump to definitions normally, and go test ./... in the right context actually sees the whole forest rather than a single tree.

Switching dependency configurations

Sometimes you need to test a project under different conditions: “what happens if the library is taken locally?” and “what happens if it’s taken as a normal dependency?” Workspaces let you keep different go.work files (in different folders) or even a single go.work where you temporarily comment out or remove use for certain modules.

A small table to reinforce the difference between the approaches:

8. Common mistakes when working with go.work

Mistake No. 1: adding a package subfolder to use instead of the module root.
It’s very tempting to write use ./todolib/task, because you need the task package. But a workspace operates at the module level, and a module is defined by the go.mod file. So in use you must specify the directory that contains go.mod. Otherwise you’ll get weird symptoms: imports won’t resolve, the IDE won’t understand the structure, and you’ll start suspecting that Go is just being stubborn (when it’s merely following the rules literally).

Mistake No. 2: expecting go.work to “replace” go.mod.
go.work is not a “new go.mod,” but an external context for multiple modules. Each module still has its own go.mod, and that’s its “passport.” The workspace only tells Go tools: “consider these passports together.”

Mistake No. 3: not checking whether workspace mode is enabled and debugging the wrong reality.
If GOWORK does not point to a .work file, workspace mode is not active, and Go will work “as usual.” Checking go env GOWORK (empty vs. not empty) often saves hours of life and a couple of nerve cells.

Mistake No. 4: keeping go.work as a “permanent global setting” and forgetting it affects builds.
go.work is a development tool. It’s convenient, but it also changes context: dependencies can be taken locally. That’s great when you’re consciously developing. But if you run checks, builds, or share instructions with a team, it’s important to know whether a workspace is being used—and whether it’s the same for everyone.

Mistake No. 5: treating go work sync as “fix everything.”
go work sync is genuinely useful, but it’s not magic. It modifies the modules’ go.mod files, which affects the dependency contract. Use it when you understand what you want to sync—not when “something doesn’t work and I pressed the button.”