1# Setting up your workspace 2 3`gopls` supports both Go module and GOPATH modes. However, it needs a defined 4scope in which language features like references, rename, and implementation 5should operate. 6 7The following options are available for configuring this scope: 8 9## Module mode 10 11### One module 12 13If you are working with a single module, you can open the module root (the 14directory containing the `go.mod` file), a subdirectory within the module, 15or a parent directory containing the module. 16 17**Note**: If you open a parent directory containing a module, it must **only** 18contain that single module. Otherwise, you are working with multiple modules. 19 20### Multiple modules 21 22As of Jan 2020, if you are working with multiple modules, you will need to 23create a "workspace folder" for each module. This means that each module has 24its own scope, and features will not work across modules. We are currently 25working on addressing this limitation--see details about 26[experimental workspace module mode](#experimental-workspace-module-mode) 27below. 28 29In VS Code, you can create a workspace folder by setting up a 30[multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces). 31View the [documentation for your editor plugin](user.md#editor) to learn how to 32configure a workspace folder in your editor. 33 34#### Workspace module (experimental) 35 36Many `gopls` users would like to work with multiple modules at the same time 37([golang/go#32394](https://github.com/golang/go/issues/32394)), and 38specifically, have features that work across modules. We plan to add support 39for this via a concept called the "workspace module", which is described in 40[this design document](https://github.com/golang/proposal/blob/master/design/37720-gopls-workspaces.md). 41This feature works by creating a temporary module that requires all of your 42workspace modules, meaning all of their dependencies must be compatible. 43 44The workspace module feature is currently available as an opt-in experiment, 45and it will allow you to work with multiple modules without creating workspace 46folders for each module. You can try it out by configuring the 47[experimentalWorkspaceModule](settings.md#experimentalworkspacemodule-bool) 48setting. If you try it and encounter issues, please 49[report them](https://github.com/golang/go/issues/new) so we can address them 50before the feature is enabled by default. 51 52You can follow our progress on the workspace module work by looking at the 53open issues in the 54[gopls/workspace-module milestone](https://github.com/golang/go/milestone/179). 55 56### GOPATH mode 57 58When opening a directory within your GOPATH, the workspace scope will be just 59that directory. 60 61### At your own risk 62 63Some users or companies may have projects that encompass one `$GOPATH`. If you 64open your entire `$GOPATH` or `$GOPATH/src` folder, the workspace scope will be 65your entire `GOPATH`. If your GOPATH is large, `gopls` to be very slow to start 66because it will try to find all of the Go files in the directory you have 67opened. It will then load all of the files it has found. 68 69To work around this case, you can create a new `$GOPATH` that contains only the 70packages you want to work on. 71 72--- 73 74If you have additional use cases that are not mentioned above, please 75[file a new issue](https://github.com/golang/go/issues/new). 76