Back to list2023-222

Debugging Rust with NeoVim

First things first. I use AstroNvim as a baseline configuration with a custom user configuration. If you're interested you can find my Astronvim config right here.

AstroNvim uses nvim-dap as a debugging interface. This is important to understand when you're looking for debugging configurations as it's not the only method available. If you're not running nvim-dap this article may not help you at all.

Install DAP modules and system packages

To make nvim-dap work with Rust you need to install two dap modules: codelldb and cpptools using the mason package manager.

Nvim mason DAP list showing codelldb and cpptools installed

You may choose to add them to your user config to ensure automatic installation accross your devices using this config. To do so edit the file containing your mason package list. For example: ~/.config/nvim/lua/user/plugins/mason.lua and edit it in a way like this:

-- ... Other code above ...
   -- overrides `require("mason-nvim-dap").setup(...)`
   opts = function(_, opts)
     -- add more things to the ensure_installed table protecting against community packs modifying it
     opts.ensure_installed = require("astronvim.utils").list_insert_unique(opts.ensure_installed, {

Next install the lldb package. On Arch that would be:

pacman -Sy lldb codelldb

Enable Per Project configuration with nvim-dap-projects

The official AstroNvim Debugger config documentation focusses on setting up the debugger in one central place. This generally works but I found it very restrictive.

Instead I prefer to use a per project configuration. This is based on another module called nvim-dap-projects. The author also posted this video on YouTube showing and explaining the mechanism to some extent.

Install the package through your user config. Add a file like ~/.config/nvim/lua/user/plugins/dap-projects.lua:

return {

Next, make sure to init the package. I'm doing this in the polish function of my user config. By default that one is located in ~/.config/nvim/lua/user/init.lua. Find the polish funcation and add the following line:

-- ... other stuff ...

This one line cost me a lot of time to figure out ...

Restart NeoVim and mason should take care of the installation.

Set up a project configuration

Finally set up a configuration for your project in ${PROJECTROOT}/.nvim-dap.lua. Example:

local dap = require("dap")

dap.adapters.lldb = {
    type = "executable",
    command = "/usr/bin/lldb-vscode", -- adjust as needed
    name = "lldb",

dap.configurations.rust = {
        name = "hello-world",
        type = "lldb",
        request = "launch",
        program = function()
            return vim.fn.getcwd() .. "/target/debug/hello-world"
        cwd = "${workspaceFolder}",
        stopOnEntry = false,
        name = "hello-dap",
        type = "lldb",
        request = "launch",
        program = function()
            return vim.fn.getcwd() .. "/target/debug/hello-dap"
        cwd = "${workspaceFolder}",
        stopOnEntry = false,

This configuration sets up two debugging configurations. One for hello-world the other one for hello-dap.

Make sure to compile the debug build before running the debugger. nvim-dap will not do it for you. However I'd be keen on finding a solution to automate this. Let me know if you have any ideas on how to get this done.

Open Nvim in your project root directory. A notification from nvim-dap should notify you that a local configuration file was found.

nvim-dap-projects notification showing that it found a local config

Set a breakpoint (AstroNvim default: F9) and start your debugger (AstroNvim Shortcut F5) and you should be greeted with a selection of configs you can choose to run.

nvim-dap config selection menu showing hello-world and hello-dap

Choose the config that suits your code and off you go.

successfully debugging rust code :)

If you run into trouble setting this up check out my entire AstroNvim config. Maybe it holds the solution to a problem.

nvim-dap for other languages

Rust is not the only language supported by this setup. In fact it will work just fine with C, C++, etc. Beyond that it's not difficult to set up a Python debugging environment as well.

The capability to run a debugging session in the console based NeoVim is quite powerful. Especially when you cannot connect other debuggers (e.g. PyCharm) to some remote environment. So it's very useful to have even if you don't normally code in NeoVim.

Have a lot of fun!