6.8 KiB
gopls, the Go language server
gopls (pronounced "Go please") is the official Go language server developed
by the Go team.
It provides a wide variety of IDE features
to any LSP-compatible editor.
You should not need to interact with gopls directly--it will be automatically
integrated into your editor. The specific features and settings vary slightly
by editor, so we recommend that you proceed to the
documentation for your editor below.
Also, the gopls documentation for each feature describes whether it is
supported in each client editor.
Editors
To get started with gopls, install an LSP plugin in your editor of choice.
TODO: ensure that each editor has a local page (and move these to doc/clients/$EDITOR.md). TODO: also, be more consistent about editor (e.g. Emacs) vs. client (e.g. eglot).
If you use gopls with an editor that is not on this list, please send us a CL
updating this documentation.
Installation
For the most part, you should not need to install or update gopls. Your
editor should handle that step for you.
If you do want to get the latest stable version of gopls, run the following
command:
go install golang.org/x/tools/gopls@latest
Learn more in the advanced installation instructions.
Learn more about gopls releases in the release policy.
Setting up your workspace
gopls supports both Go module, multi-module and GOPATH modes. See the
workspace documentation for information on supported
workspace layouts.
Configuration
You can configure gopls to change your editor experience or view additional
debugging information. Configuration options will be made available by your
editor, so see your editor's instructions for specific details. A
full list of gopls settings can be found in the settings documentation.
Environment variables
gopls inherits your editor's environment, so be aware of any environment
variables you configure. Some editors, such as VS Code, allow users to
selectively override the values of some environment variables.
Support Policy
Gopls is maintained by engineers on the Go tools team, who actively monitor the Go and VS Code Go issue trackers.
Supported Go versions
gopls follows the
Go Release Policy, meaning
that it officially supports only the two most recent major Go releases. Until
August 2024, the Go team will also maintain best-effort support for the last
4 major Go releases, as described in issue #39146.
When using gopls, there are three versions to be aware of:
- The gopls build go version: the version of Go used to build gopls.
- The go command version: the version of the go list command executed by gopls to load information about your workspace.
- The language version: the version in the go directive of the current file's enclosing go.mod file, which determines the file's Go language semantics.
Starting with the release of Go 1.23.0 and gopls@v0.17.0 in August 2024, we will only support the most recent Go version as the gopls build go version. However, due to the forward compatibility support added in Go 1.21, as long as Go 1.21 or later are used to install gopls, any necessary toolchain upgrade will be handled automatically, just like any other dependency.
Additionally, starting with gopls@v0.17.0, the go command version will narrow from 4 versions to 3. This is more consistent with the Go Release Policy.
Gopls supports all Go versions as its language version, by providing compiler errors based on the language version and filtering available standard library symbols based on the standard library APIs available at that Go version.
Maintaining support for building gopls with legacy versions of Go caused significant friction for gopls maintainers and held back other improvements. If you are unable to install a supported version of Go on your system, you can still install an older version of gopls. The following table shows the final gopls version that supports a given Go version. Go releases more recent than those in the table can be used with any version of gopls.
| Go Version | Final gopls version with support (without warnings) |
|---|---|
| Go 1.12 | gopls@v0.7.5 |
| Go 1.15 | gopls@v0.9.5 |
| Go 1.17 | gopls@v0.11.0 |
| Go 1.18 | gopls@v0.14.2 |
| Go 1.20 | gopls@v0.15.3 |
Supported build systems
gopls currently only supports the go command, so if you are using
a different build system, gopls will not work well. Bazel is not officially
supported, but may be made to work with an appropriately configured
go/packages driver. See
bazelbuild/rules_go#512
for more information.
You can follow these instructions
to configure your gopls to work with Bazel.
Troubleshooting
If you are having issues with gopls, please follow the steps described in the
troubleshooting guide.