gopls (pronounced “Go please”) is the official language server for Go, 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.
This documentation (https://go.dev/gopls) describes the most recent release of gopls. To preview documentation for the release under development, visit https://tip.golang.org/gopls.
Gopls supports a wide range of standard LSP features for navigation, completion, diagnostics, analysis, and refactoring, and a number of additional features not found in other language servers.
See the Index of features for complete documentation on what Gopls can do for you.
To get started with gopls, install an LSP plugin in your editor of choice.
If you use gopls with an editor that is not on this list, please send us a CL updating this documentation.
To install the latest stable release of gopls, run the following command:
go install golang.org/x/tools/gopls@latest
Some editors, such as VS Code, will handle this step for you, and ensure that Gopls is updated when a new stable version is released.
After updating, you may need to restart running Gopls processes to observe the effect. Each client has its own way to restart the server. (On a UNIX machine, you can use the command killall gopls.)
Learn more in the advanced installation instructions.
Gopls releases follow semantic versioning, with major changes and new features introduced only in new minor versions (i.e. versions of the form v*.N.0 for some N). Subsequent patch releases contain only cherry-picked fixes or superficial updates.
In order to align with the Go release timeline, we aim to release a new minor version of Gopls approximately every three months, with patch releases approximately every month, according to the following table:
| Month | Version(s) |
|---|---|
| Jan | v*.<N+0>.0 |
| Jan-Mar | v*.<N+0>.* |
| Apr | v*.<N+1>.0 |
| Apr-Jun | v*.<N+1>.* |
| Jul | v*.<N+2>.0 |
| Jul-Sep | v*.<N+2>.* |
| Oct | v*.<N+3>.0 |
| Oct-Dec | v*.<N+3>.* |
For more background on this policy, see https://go.dev/issue/55267.
gopls supports both Go module, multi-module and GOPATH modes. See the workspace documentation for information on supported workspace layouts.
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.
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.
Gopls is maintained by engineers on the Go tools team, who actively monitor the Go and VS Code Go issue trackers.
gopls follows the Go Release Policy, meaning that it officially supports only the two most recent major Go releases.
When using gopls, there are three versions to be aware of:
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 |
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.
If you are having issues with gopls, please follow the steps described in the troubleshooting guide.