Beth Brown, for the Go team
5 April 2022

Go 1.18 adds workspace mode to Go, which lets you work on multiple modules

You can get Go 1.18 by visiting the download page. The
release notes have more details about all the


Workspaces in Go 1.18 let you work on
multiple modules simultaneously without having to edit go.mod files for each
module. Each module within a workspace is treated as a root module when
resolving dependencies.

Previously, to add a feature to one module and use it in another module, you
needed to either publish the changes to the first module, or edit the
file of the dependent
module with a replace directive for your local, unpublished module changes. In
order to publish without errors, you had to remove the replace directive from
the dependent module’s go.mod file after you published the local changes to
the first module.

With Go workspaces, you control all your dependencies using a file in
the root of your workspace directory. The file has use and
replace directives that override the individual go.mod files, so there is
no need to
edit each go.mod file individually.

You create a workspace by running go work init with a list of module
directories as space-separated arguments. The workspace doesn’t need to contain
the modules you’re working with. The init command creates a file
that lists modules in the workspace. If you run go work init without
arguments, the command creates an empty workspace.

To add modules to the workspace, run go work use [moddir] or manually edit
the file. Run go work use -r to recursively add directories in the
argument directory with a go.mod file to your workspace. If a directory
doesn’t have a go.mod file, or no longer exists, the use directive for that
directory is removed from your file.

The syntax of a file is similar to a go.mod file and contains the
following directives:

  • go: the go toolchain version e.g. go 1.18
  • use: adds a module on disk to the set of main modules in a workspace.
    Its argument is a relative path to the directory containing the module’s
    go.mod file. A use directive doesn’t add modules in subdirectories of
    the specified directory.
  • replace: Similar to a replace directive in a go.mod file, a
    replace directive in a file replaces the contents of a
    specific version of a module, or all versions of a module, with
    contents found elsewhere.


Workspaces are flexible and support a variety of workflows. The following
sections are a brief overview of the ones we think will be the most common.

Add a feature to an upstream module and use it in your own module

  1. Create a directory for your workspace.

  2. Clone the upstream module you want to edit. If you haven’t contributed to
    Go before, read the contribution guide.

  3. Add your feature to the local version of the upstream module.

  4. Run go work init [path-to-upstream-mod-dir] in the workspace folder.

  5. Make changes to your own module in order to implement the feature added
    to the upstream module.

  6. Run go work use [path-to-your-module] in the workspace folder.

    The go work use command adds the path to your module to your

    go 1.18
    use (
  7. Run and test your module using the new feature added to the upstream module.

  8. Publish the upstream module with the new feature.

  9. Publish your module using the new feature.

Work with multiple interdependent modules in the same repository

While working on multiple modules in the same repository, the file
defines the workspace instead of using replace directives in each module’s
go.mod file.

  1. Create a directory for your workspace.

  2. Clone the repository with the modules you want to edit. The modules don’t
    have to be in your workspace folder as you specify the relative path to
    each with the use directive.

  3. Run go work init [path-to-module-one] [path-to-module-two] in your
    workspace directory.

    Example: You are working on which depends
    on other packages in the module.

    You clone the repository and then run go work init tools tools/groundhog in
    your workspace folder.

    The contents of your file resemble the following:

    go 1.18
    use (

    Any local changes made in the tools module will be used by
    tools/groundhog in your workspace.

Switching between dependency configurations

To test your modules with different dependency configurations you can either
create multiple workspaces with separate files, or keep one workspace
and comment out the use directives you don’t want in a single

To create multiple workspaces:

  1. Create separate directories for different dependency needs.
  2. Run go work init in each of your workspace directories.
  3. Add the dependencies you want within each directory via go work use [path-to-dependency].
  4. Run go run [path-to-your-module] in each workspace directory to use the
    dependencies specified by its file.

To test out different dependencies within the same workspace, open the
file and add or comment out the desired dependencies.

Still using GOPATH?

Maybe using workspaces will change your mind. GOPATH users can resolve their
dependencies using a file located at the base of their GOPATH
directory. Workspaces don’t aim to completely recreate all GOPATH workflows,
but they can create a setup that shares some of the convenience of GOPATH
while still providing the benefits of modules.

To create a workspace for GOPATH:

  1. Run go work init in the root of your GOPATH directory.
  2. To use a local module or specific version as a dependency in your
    workspace, run go work use [path-to-module].
  3. To replace existing dependencies in your modules’ go.mod files use
    go work replace [path-to-module].
  4. To add all the modules in your GOPATH or any directory, run go work use -r to recursively add directories with a go.mod file to your workspace.
    If a directory doesn’t have a go.mod file, or no longer exists, the use
    directive for that directory is removed from your file.

Note: If you have projects without go.mod files that you want to add to
the workspace, change into their project directory and run go mod init,
then add the new module to your workspace with go work use [path-to-module].

Workspace commands

Along with go work init and go work use, Go 1.18 introduces the following
commands for workspaces:

  • go work sync: pushes the dependencies in the file back into
    the go.mod files of each workspace module.
  • go work edit: provides a command-line interface for editing,
    for use primarily by tools or scripts.

Module-aware build commands and some go mod subcommands examine the GOWORK
environment variable to determine if they are in a workspace context.

Workspace mode is enabled if the GOWORK variable names a path to a file that
ends in .work. To determine which file is being used, run
go env GOWORK. The output is empty if the go command is not in workspace

When workspace mode is enabled, the file is parsed to determine the
three parameters for workspace mode: A Go version, a list of directories, and a
list of replacements.

Some commands to try in workspace mode (provided you already know what they

go work init
go work sync
go work use
go list
go build
go test
go run
go vet

Editor experience improvements

We’re particularly excited about the upgrades to Go’s language server
gopls and the
VSCode Go extension
that make working with multiple modules in an LSP-compatible editor a smooth
and rewarding experience.

Find references, code completion, and go to definitions work across modules
within the workspace. Version 0.8.1
of gopls introduces diagnostics, completion, formatting, and hover for files. You can take advantage of these gopls features with any
LSP-compatible editor.

Editor specific notes

  • The latest vscode-go
    quick access to your workspace’s file via the Go status bar’s
    Quick Pick menu.

Access the file via the Go status bar’s Quick Pick menu

  • GoLand supports workspaces and has
    plans to add syntax highlighting and code completion for files.

For more information on using gopls with different editors see the gopls

What’s next?


Leave a Reply

Your email address will not be published. Required fields are marked *