ray-x/go.nvim: a Go toolkit for Neovim built on gopls and treesitter

What go.nvim adds on top of a plain gopls setup

Neovim's built-in LSP client plus gopls already gives you completion, hover, references and rename. What it does not give you is the layer of Go-specific editing operations that Go developers reach for constantly: filling a struct literal from its type, generating an if err != nil block, producing interface method stubs, converting JSON to a struct, adding or removing struct tags, and switching between a file and its test. go.nvim is a Lua plugin that implements those operations, some through gopls code actions and some through treesitter and the Go AST.

The audience is narrow and specific. You need to be a Neovim user who works in Go and who is comfortable configuring plugins in Lua. The README describes it as covering "most features required for a gopher", and the command list backs that up: build, test, coverage, debug, lint, module commands, vulnerability scanning, doc comments, snippets. If you write Go occasionally in another editor, the setup cost is not repaid. If Neovim is your daily driver and Go is your daily language, the command surface is the point.

How the plugin is put together: gopls, treesitter, libuv and external binaries

There are three distinct mechanisms under the hood, and knowing which one a command uses tells you what can break.

The first is gopls. Navigation, inlay hints, CodeLens, CodeAction, and several refactors such as fillstruct and organize imports are routed through the language server. That means their behaviour tracks your gopls version, not the plugin's. The README notes inlay hints need gopls 0.9+ and are enabled by default in 0.10+.

The second is treesitter and the Go AST. Commands like GoIfErr, GoFillStruct, GoFillSwitch, GoFixPlurals and GoGenReturn are described as powered by treesitter and the Go AST. These run locally in the editor, which makes them fast, but it also means they depend on a working Go parser. The installation notes say to run TSInstall go for the parser.

The third is external command-line tools. Test generation uses gotests, mocks use mockgen, tag editing uses gomodifytags, linting uses golangci-lint v2, formatting can use gofumpt or goimports, vulnerability scanning uses govulncheck, and tests can run under go test, gotestsum or ginkgo. Async jobs are wrapped with libuv throughout, so these do not block the editor. The practical consequence is that go.nvim is partly a coordinator: when a command fails, the failure is often in a binary the plugin invoked rather than in the plugin's own Lua.

Installing go.nvim with lazy.nvim and running goimports on save

The README gives a lazy.nvim spec directly. The dependency block lists ray-x/guihua.lua and neovim/nvim-lspconfig, with nvim-treesitter marked optional for the master version. The opts function calls require("go").setup(opts) and registers a BufWritePre autocmd on *.go that runs goimports, so formatting happens on every save.

{
  "ray-x/go.nvim",
  dependencies = {
    "ray-x/guihua.lua",
    "neovim/nvim-lspconfig",
  },
  opts = function()
    require("go").setup(opts)
    return {}
  end,
  event = {"CmdlineEnter"},
  ft = {"go", "gomod"},
  build = ':lua require("go.install").update_all_sync()'
}

The build key runs the installer synchronously, which is how the external binaries get onto disk. If you omit it, you install them yourself. The README also recommends running TSInstall go if the Go parser is missing, and states that sed is recommended for the plugin to run.

Before any of that, check that the Go binary directory is reachable from your shell, because go.nvim shells out to tools that live there.

echo $PATH | grep "$GOPATH/bin"

If nothing prints, the README suggests adding the directory to your shell config with export PATH=$PATH:$GOPATH/bin. A first real use after setup is opening a .go file and invoking GoIfErr on a line that returns an error, or GoImpl on an interface name to generate method stubs. Both are documented in doc/usage.md.

The Neovim 0.11 problem and other places go.nvim gets in your way

The clearest limitation is versioning. The README states that nvim-treesitter was archived during a refactor to its main branch, that the plugin no longer requires nvim-treesitter, and that the master version requires Neovim 0.12. It then says plainly: "I do not guarantee the behavior of nvim 0.11 will still be correct." For 0.11 users the documented path is the v0.11 release, whose own release note describes it as the release for the treesitter master version and Neovim 0.11. This is a real fork in the road. If you run Neovim 0.11 and follow the master branch install instructions, you are outside what the author supports.

The second limitation is dependency surface. The plugin is a thin layer over a long list of binaries: gopls, gotests, mockgen, gomodifytags, golangci-lint v2, gofumpt, goimports, govulncheck, dlv, and optionally gotestsum or ginkgo. Each has its own version compatibility. golangci-lint is pinned to v2 in the README, which is a signal that v1 configurations are not the target. The install helper exists precisely because keeping this set current is tedious.

The third is scope. go.nvim does not replace gopls, and it does not manage your Go toolchain. If gopls is misconfigured or your GOPATH is wrong, no amount of plugin configuration compensates. The README's own troubleshooting step is about PATH, not about plugin options.

go.nvim versus assembling lspconfig, nvim-dap and null-ls yourself

The realistic alternative is not a single competing plugin but the do-it-yourself stack: neovim/nvim-lspconfig for gopls, mfussenegger/nvim-dap with rcarriga/nvim-dap-ui for debugging, and a formatter or linter bridge for goimports and golangci-lint. The repository's own topics list null-ls and nvim-dap, which tells you what go.nvim is standing in for.

The difference in approach is integration versus composition. In the DIY stack you configure each piece and you own every keymap, every autocmd and every version bump. You get exactly the behaviour you wrote, and nothing happens that you did not ask for. go.nvim instead ships a command set and a zero-config Go DAP adapter, and the README states it can load VSCode launch.json configurations, so debug setups carry over from another editor. The cost is that you inherit the plugin's choices: its default keymaps, its default formatter wiring, its assumptions about which binaries exist. The README does expose lsp_keymaps as an option in the lazy spec, so the keymap layer is at least adjustable.

If your Neovim config is already a hand-tuned LSP setup, adding go.nvim means auditing for overlap. If your config is thin and you want Go support now, starting from the plugin and disabling what you dislike is less work.

Maintenance cadence, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-11. The most recent release is v0.11 from 2026-04-08, preceded by v0.10.4 in April 2025 and v0.10.0 in February 2025. The release naming tracks Neovim and treesitter versions rather than a fixed cadence, so an upgrade is not a routine version bump: moving from v0.11 to master also moves you from Neovim 0.11 to 0.12, and the README explicitly declines to guarantee the older combination.

Upgrade cost therefore concentrates in two places. First, the Neovim and treesitter versions, which the release notes tie together. Second, the external binaries, which require("go.install").update_all_sync() updates in one call. The repository also carries a Makefile with a test target that runs PlenaryBustedDirectory under a headless Neovim, plus lint via luacheck on lua/go, so there is a test harness you can run against your own checkout if you want to check a change before adopting it.

The licence is MIT, which permits commercial and private use and modification. That is a permissive licence, and it says nothing about the licences of the external tools the plugin invokes; if you vendor go.nvim into a distributed product, the binaries it shells out to are a separate question. This is not legal advice, and the plugin's own LICENSE file is the authority.

Editorial conclusion

Adopt go.nvim if you already run gopls and treesitter in Neovim and want GoIfErr, GoImpl, GoTest and the DAP adapter wired up without assembling them yourself. Skip it if you are on Neovim 0.11 and unwilling to pin the v0.11 release, since the README says master requires 0.12 and does not guarantee 0.11 behaviour. Before committing, verify two things on your machine: that $GOPATH/bin is on $PATH, and whether you need require("go.install").update_all_sync() to pull the external binaries the plugin shell outs to.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. ray-x/go.nvim on GitHub
4. README
5. Releases