Multi-Module Workspaces

Why workspaces?

When you develop a library and its consumer at the same time, Go normally fetches the library from the module cache — the published version. To use local changes, you'd add replace directives in go.mod. That's fragile and easy to accidentally commit. Workspaces solve this cleanly.

Create a module

Start by setting up a directory and initializing a new Go module that imports an external package.

$ mkdir workspace && cd workspace
$ mkdir hello && cd hello
$ go mod init example.com/hello
go: creating new go.mod: module example.com/hello
$ go get golang.org/x/example/hello/reverse

Now create the entry point that uses the reverse package:

package main

import (
    "fmt"

    "golang.org/x/example/hello/reverse"
)

func main() {
    fmt.Println(reverse.String("Hello"))
}

$ go run .
olleH

Initialize the workspace

Go back to the workspace root and create a go.work file. This tells Go which modules belong to your local workspace.

$ cd workspace
$ go work init ./hello

This generates a go.work file:

go 1.18

use ./hello

Run from the workspace root

With the workspace active, you can build and run any module from the root directory — Go resolves all use-listed modules automatically.

$ go run ./hello
olleH

Add a local dependency

Clone the dependency's repository and add it to the workspace. Now Go resolves imports from your local copy instead of the module cache.

$ git clone https://go.googlesource.com/example
Cloning into 'example'...
$ go work use ./example/hello

The go.work file now includes both modules:

go 1.18

use (
    ./hello
    ./example/hello
)

Modify and use the dependency

Add a new function to the cloned reverse package and immediately use it from your hello module — no publishing required.

Create a new file in the cloned dependency:

package reverse

import "strconv"

// Int returns the decimal reversal of the integer i.
func Int(i int) int {
    i, _ = strconv.Atoi(String(strconv.Itoa(i)))
    return i
}

Update your module to call the new function:

package main

import (
    "fmt"

    "golang.org/x/example/hello/reverse"
)

func main() {
    fmt.Println(reverse.String("Hello"), reverse.Int(24601))
}

$ go run ./hello
olleH 10642

Release and clean up

When you're done developing, release the modified dependency, pin the version in your go.mod, and retire the workspace.

Workspace commands

The full lifecycle