Explore the docs »

Report Bug · Request Feature · Ask Question

Supercharge your Rust experience in Neovim!
A heavily modified fork of rust-tools.nvim

🦀

• Installation
• Quick setup
• Usage
• Advanced configuration
• Troubleshooting
• FAQ
• Migrating from rust-tools

• neovim >= 0.9
• rust-analyzer

• dot from graphviz, for crate graphs.
• cargo, required for Cargo projects.
• A debug adapter (e.g. lldb or codelldb) and nvim-dap, required for debugging.

This plugin is available on LuaRocks:

:Rocks install rustaceanvim

Example using lazy.nvim:

{
  'mrcjkb/rustaceanvim',
  version = '^3', -- Recommended
  ft = { 'rust' },
}

To manually generate documentation, use :helptags ALL.

Look at the configuration information below to get started.

This plugin automatically configures the rust-analyzer builtin LSP client and integrates with other Rust tools. See the Usage section for more info.

This is a filetype plugin that works out of the box, so there is no need to call a setup function or configure anything to get this plugin working.

You will most likely want to add some keymaps. Most keymaps are only useful in rust files, so I suggest you define them in ~/.config/nvim/after/ftplugin/rust.lua¹

Example:

vim.g.rustaceanvim = {
  server = {
    on_attach = function(client, bufnr)
      -- semantic highlighting is poorly supported by many themes. It also causes the colors to change after rust-analyzer ran.
      client.server_capabilities.semanticTokensProvider = nil
      -- Map leader a to code actions
      vim.keymap.set( "n", "<Leader>a", function() vim.cmd.RustLsp('codeAction') end, { silent = true, buffer = bufnr })
      end,
  }
}

:RustLsp debuggables [last?]

vim.cmd.RustLsp {'debuggables', 'last' --[[ optional ]] }

:RustLsp runnables [last?]

vim.cmd.RustLsp {'runnables', 'last' --[[ optional ]] }

:RustLsp expandMacro

vim.cmd.RustLsp('expandMacro')

:RustLsp rebuildProcMacros

vim.cmd.RustLsp('rebuildProcMacros')

:RustLsp moveItem up
:RustLsp moveItem down

vim.cmd.RustLsp { 'moveItem',  'up' }
vim.cmd.RustLsp { 'moveItem',  'down' }

:RustLsp hover actions

vim.cmd.RustLsp { 'hover', 'actions' }

:RustLsp hover range

vim.cmd.RustLsp { 'hover', 'range' }

:RustLsp explainError

vim.cmd.RustLsp('explainError')

:RustLsp openCargo

vim.cmd.RustLsp('openCargo')

:RustLsp parentModule

vim.cmd.RustLsp('parentModule')

:RustLsp joinLines

vim.cmd.RustLsp('joinLines')

:RustLsp ssr [query]

vim.cmd.RustLsp { 'ssr', '<query>' --[[ optional ]] }

:RustLsp crateGraph [backend [output]]

vim.cmd.RustLsp { 'crateGraph', '[backend]', '[output]' }

:RustLsp syntaxTree

vim.cmd.RustLsp('syntaxTree')

:RustLsp flyCheck [run?|clear?|cancel?]

vim.cmd.RustLsp('flyCheck') -- defaults to 'run'
vim.cmd.RustLsp { 'flyCheck', 'run' }
vim.cmd.RustLsp { 'flyCheck', 'clear' }
vim.cmd.RustLsp { 'flyCheck', 'cancel' }

:RustLsp view [hir|mir]

vim.cmd.RustLsp { 'view', 'hir' }
vim.cmd.RustLsp { 'view', 'mir' }

To modify the default configuration, set vim.g.rustaceanvim.

• See :help rustaceanvim.config for a detailed documentation of all available configuration options. You may need to run :helptags ALL if the documentation has not been installed.
• The default configuration can be found here (see RustaceanDefaultConfig).
• For detailed descriptions of the language server configs, see the rust-analyzer documentation.

The options shown below are the defaults. You only need to pass the keys to the setup function that you want to be changed, because the defaults are applied for keys that are not provided.

Example config:

vim.g.rustaceanvim = {
  -- Plugin configuration
  tools = {
  },
  -- LSP configuration
  server = {
    on_attach = function(client, bufnr)
      -- you can also put keymaps in here
    end,
    settings = {
      -- rust-analyzer language server configuration
      ['rust-analyzer'] = {
      },
    },
  },
  -- DAP configuration
  dap = {
  },
}

For Rust, codelldb from the CodeLLDB VSCode extension provides a better experience than lldb. If you are using a distribution that lets you install the codelldb executable, this plugin will automatically detect it and configure itself to use it as a debug adapter.

Some examples:

• NixOS: vscode-extensions.vadimcn.vscode-lldb.adapter
• Arch Linux: codelldb-bin (AUR)
• Using mason.nvim: :MasonInstall codelldb

If your distribution does not have a codelldb package, you can configure it as follows:

1. Install the CodeLLDB VSCode extension.
2. Find out where it is installed. On Linux, this is typically in $HOME/.vscode/extensions/
3. Update your configuration:

vim.g.rustaceanvim = function()
  -- Update this path
  local extension_path = vim.env.HOME .. '/.vscode/extensions/vadimcn.vscode-lldb-1.10.0/'
  local codelldb_path = extension_path .. 'adapter/codelldb'
  local liblldb_path = extension_path .. 'lldb/lib/liblldb'
  local this_os = vim.uv.os_uname().sysname;

  -- The path is different on Windows
  if this_os:find "Windows" then
    codelldb_path = extension_path .. "adapter\\codelldb.exe"
    liblldb_path = extension_path .. "lldb\\bin\\liblldb.dll"
  else
    -- The liblldb extension is .so for Linux and .dylib for MacOS
    liblldb_path = liblldb_path .. (this_os == "Linux" and ".so" or ".dylib")
  end

  local cfg = require('rustaceanvim.config')
  return {
    dap = {
      adapter = cfg.get_codelldb_adapter(codelldb_path, liblldb_path),
    },
  }
end

By default, this plugin will look for a rust-analyzer.json file in the project root directory, and attempt to load it. If the file does not exist, or it can't be decoded, the default settings will be used.

You can change this behaviour with the server.settings config:

vim.g.rustaceanvim = {
  -- ...
  server = {
    ---@param project_root string Path to the project root
    settings = function(project_root)
      local ra = require('rustaceanvim.config.server')
      return ra.load_rust_analyzer_settings(project_root, {
        settings_file_pattern = 'rust-analyzer.json'
      })
    end,
  },
}

For a health check, run :checkhealth rustaceanvim

To open the rust-analyzer log file, run :RustLsp logFile.

To troubleshoot this plugin with a minimal config in a temporary directory, you can try minimal.lua.

mkdir -p /tmp/minimal/
NVIM_DATA_MINIMAL="/tmp/minimal" NVIM_APP_NAME="nvim-minimal" nvim -u minimal.lua

If you cannot reproduce your issue with a minimal config, it may be caused by another plugin, or a setting of your plugin manager. In this case, add additional plugins and configurations to minimal.lua, until you can reproduce it.

For issues related to rust-analyzer (e.g. LSP features not working), see also the rust-analyzer troubleshooting guide.

As Neovim >= 0.10 supports inlay hints natively, I have removed the code from this plugin.

To enable inlay hints in Neovim < 0.10, see this discussion.

• simrat39/rust-tools.nvim This plugin is a heavily modified fork of rust-tools.nvim.
• Saecki/crates.nvim
• vxpm/ferris.nvim Geared towards people who prefer manual LSP client configuration. Has some features that have not yet been implemented by this plugin.

rust-tools.nvim draws inspiration from akinsho/flutter-tools.nvim