Frequently Asked Questions

How do I use a plugin not implemented in nixvim

Using a plugin not supported by nixvim, but packaged in nixpkgs is straightforward:

• Register the plugin through extraPlugins: extraPlugins = [pkgs.vimPlugins."<plugin name>"].
• Configure the plugin through extraConfigLua: extraConfigLua = "require('my-plugin').setup({foo = "bar"})";

How do I use a plugin not packaged in nixpkgs

This is straightforward too, you can add the following to extraPlugins for a plugin hosted on GitHub:

extraPlugins = [(pkgs.vimUtils.buildVimPlugin {
    name = "my-plugin";
    src = pkgs.fetchFromGitHub {
        owner = "<owner>";
        repo = "<repo>";
        rev = "<commit hash>";
        hash = "<nix NAR hash>";
    };
})];

The nixpkgs manual has more information on this.

How do I solve "<name> cannot be found in pkgs"

When using Nixvim, it is possible to encounter errors about something not being found in pkgs. For example:

 … while evaluating the attribute 'optionalValue.value'

   at /nix/store/XXX-source/lib/modules.nix:868:5:
    867|
    868|     optionalValue =
       |     ^
    869|       if isDefined then { value = mergedValue; }

 … while evaluating a branch condition

   at /nix/store/XXX-source/lib/modules.nix:869:7:
    868|     optionalValue =
    869|       if isDefined then { value = mergedValue; }
       |       ^
    870|       else {};

 … while evaluating the option `plugins.<name>.package':

 (stack trace truncated; use '--show-trace' to show the full, detailed trace)

 error: <name> cannot be found in pkgs

This usually means one of two things:

• The nixpkgs version is not in line with NixVim (for example nixpkgs nixos-24.11 is used with NixVim master)
• The nixpkgs unstable version used with NixVim is not recent enough.

When building nixvim using flakes and our "standalone mode", we usually recommend not declaring a "follows" for inputs.nixvim. This is so that nixvim is built against the same nixpkgs revision we're using in our test suite.

If you are building nixvim using the NixOS, home-manager, or nix-darwin modules then we advise that you keep your nixpkgs lock as close as possible to ours.

How do I create multiple aliases for a single keymap

You could use the builtin map function (or similar) to do something like this:

keymaps =
  (builtins.map (key: {
    inherit key;
    action = "<some-action>";
    options.desc = "My cool keymapping";
  }) ["<key-1>" "<key-2>" "<key-3>"])
  ++ [
    # Other keymaps...
  ];

This maps a list of keys into a list of similar keymaps. It is equivalent to:

keymaps = [
  {
    key = "<key-1>";
    action = "<some-action>";
    options.desc = "My cool keymapping";
  }
  {
    key = "<key-2>";
    action = "<some-action>";
    options.desc = "My cool keymapping";
  }
  {
    key = "<key-3>";
    action = "<some-action>";
    options.desc = "My cool keymapping";
  }
  # Other keymaps...
];

How to use system provided binaries instead of nixvim provided ones

There are a number of plugins that install extra packages using nix, but this can cause issues. For example enabling plugins.treesitter could add gcc to the PATH of neovim, and this could break workflows that rely on the system provided compiler.

Most plugins that install packages also provide a xxxPackage option that can be set to null to skip the installation of the package. For example plugin.treesitter provides the gccPackage option.