1# `gopls`, the Go language server 2 3[![PkgGoDev](https://pkg.go.dev/badge/golang.org/x/tools/gopls)](https://pkg.go.dev/golang.org/x/tools/gopls) 4 5`gopls` (pronounced "Go please") is the official Go [language server] developed 6by the Go team. It provides IDE features to any [LSP]-compatible editor. 7 8<!--TODO(rstambler): Add gifs here.--> 9 10You should not need to interact with `gopls` directly--it will be automatically 11integrated into your editor. The specific features and settings vary slightly 12by editor, so we recommend that you proceed to the [documentation for your 13editor](#editors) below. 14 15## Editors 16 17To get started with `gopls`, install an LSP plugin in your editor of choice. 18 19* [VSCode](https://github.com/golang/vscode-go/blob/master/README.md) 20* [Vim / Neovim](doc/vim.md) 21* [Emacs](doc/emacs.md) 22* [Atom](https://github.com/MordFustang21/ide-gopls) 23* [Sublime Text](doc/subl.md) 24* [Acme](https://github.com/fhs/acme-lsp) 25 26If you use `gopls` with an editor that is not on this list, please let us know 27by [filing an issue](#new-issue) or [modifying this documentation](doc/contributing.md). 28 29## Installation 30 31For the most part, you should not need to install or update `gopls`. Your 32editor should handle that step for you. 33 34If you do want to get the latest stable version of `gopls`, change to any 35directory that is both outside of your `GOPATH` and outside of a module (a temp 36directory is fine), and run: 37 38```sh 39GO111MODULE=on go get golang.org/x/tools/gopls@latest 40``` 41 42**NOTE**: Do not use the `-u` flag, as it will update your dependencies to 43incompatible versions. 44 45Learn more in the [advanced installation 46instructions](doc/advanced.md#installing-unreleased-versions). 47 48## Setting up your workspace 49 50`gopls` supports both Go module and GOPATH modes, but if you are working with 51multiple modules or uncommon project layouts, you will need to specifically 52configure your workspace. See the [Workspace document](doc/workspace.md) for 53information on supported workspace layouts. 54 55## Configuration 56 57You can configure `gopls` to change your editor experience or view additional 58debugging information. Configuration options will be made available by your 59editor, so see your [editor's instructions](#editors) for specific details. A 60full list of `gopls` settings can be found in the [Settings documentation](doc/settings.md). 61 62### Environment variables 63 64`gopls` inherits your editor's environment, so be aware of any environment 65variables you configure. Some editors, such as VS Code, allow users to 66selectively override the values of some environment variables. 67 68## Troubleshooting 69 70If you are having issues with `gopls`, please follow the steps described in the 71[troubleshooting guide](doc/troubleshooting.md). 72 73## Supported Go versions and build systems 74 75`gopls` follows the [Go Release 76Policy](https://golang.org/doc/devel/release.html#policy), meaning that it 77officially supports the last 2 major Go releases. Per 78[issue #39146](golang.org/issues/39146), we attempt to maintain best-effort 79support for the last 4 major Go releases, but this support extends only to not 80breaking the build and avoiding easily fixable regressions. 81 82Our extended support is enforced via [continuous integration with older Go 83versions](doc/contributing.md#ci). This legacy Go CI may not block releases: 84test failures may be skipped rather than fixed. Furthermore, if a regression in 85an older Go version causes irreconcilable CI failures, we may drop support for 86that Go version in CI if it is 3 or 4 Go versions old. 87 88`gopls` currently only supports the `go` command, so if you are using a 89different build system, `gopls` will not work well. Bazel support is currently 90blocked on 91[bazelbuild/rules_go#512](https://github.com/bazelbuild/rules_go/issues/512). 92 93## Additional information 94 95* [Features](doc/features.md) 96* [Command-line interface](doc/command-line.md) 97* [Advanced topics](doc/advanced.md) 98* [Contributing to `gopls`](doc/contributing.md) 99* [Integrating `gopls` with an editor](doc/design/integrating.md) 100* [Design requirements and decisions](doc/design/design.md) 101* [Implementation details](doc/design/implementation.md) 102* [Open issues](https://github.com/golang/go/issues?q=is%3Aissue+is%3Aopen+label%3Agopls) 103 104[language server]: https://langserver.org 105[LSP]: https://microsoft.github.io/language-server-protocol/ 106[Gophers Slack]: https://gophers.slack.com/ 107