Documentation | Chat

Nixvim - A Neovim configuration system for nix

• Quick set up tutorial (by @Vimjoyer)
• Nixvim: How to configure Neovim with the power of Nix (NeovimConf 2023 talk by @GaetanLepage)

What is it?

Nixvim is a Neovim distribution built around Nix modules. It is distributed as a Nix flake, and configured through Nix, all while leaving room for your plugins and your vimrc.

What does it look like?

Here is a simple configuration that uses catppuccin as the colorscheme and uses the lualine plugin:

{
  programs.nixvim = {
    enable = true;

    colorschemes.catppuccin.enable = true;
    plugins.lualine.enable = true;
  };
}

When we do this, lualine will be set up to a sensible default, and will use catppuccin as the colorscheme, no extra configuration required!

Check out this list of real world Nixvim configs!

How does it work?

When you build the module (probably using Home Manager), it will install all your plugins and generate a lua config for Neovim with all the options specified. Because it uses lua, this ensures that your configuration will load as fast as possible.

Since everything is disabled by default, it will be as snappy as you want it to be.

Plugin settings

Most plugins have a settings option, which accepts any nix attribute set and translate it into a lua table. This is then passed to the plugin's setup function. In practice this means if a plugin has a settings option, any plugin option can be configured, even if we don't explicitly have a corresponding nix option.

Raw lua

If you just want to add additional lines of lua to your init.lua, you can use extraConfigLua, extraConfigLuaPre, and extraConfigLuaPost.

If you want to assign lua code to an option that'd normally accept another type (string, int, etc), you can use Nixvim's "raw type", { __raw = "lua code"; }.

{
  some_option.__raw = "function() print('hello, world!') end";
}

{
  ['some_option'] = function() print('hello, world!') end,
}

Support/Questions

If you have any question, please use the discussions page! Alternatively, join the Matrix channel at #nixvim:matrix.org!

Installation

[!WARNING] Nixvim needs to be installed with a compatible nixpkgs version. This means that the main branch of Nixvim requires to be installed with nixpkgs-unstable.

If you want to use Nixvim with nixpkgs 26.05 you should use the nixos-26.05 branch.

For more detail, see the Installation section of our documentation.

{ pkgs, lib, ... }:
let
  nixvim = import (builtins.fetchGit {
    url = "https://github.com/nix-community/nixvim";
    # If you are not running an unstable channel of nixpkgs, select the corresponding branch of Nixvim.
    # ref = "nixos-26.05";
  });
in
{
  imports = [
    # For Home Manager
    nixvim.homeModules.nixvim
    # For NixOS
    nixvim.nixosModules.nixvim
    # For nix-darwin
    nixvim.nixDarwinModules.nixvim
  ];

  programs.nixvim.enable = true;
}

{ pkgs, lib, ... }:
{
  nix = {
    settings.experimental-features = [ "nix-command" "flakes" ];
  };
}

{
  # ...
  inputs.nixvim = {
    url = "github:nix-community/nixvim";
    # If you are not running an unstable channel of nixpkgs, select the corresponding branch of Nixvim.
    # url = "github:nix-community/nixvim/nixos-26.05";
  };
}

Usage

Nixvim can be used in four ways: through the Home Manager, nix-darwin, NixOS modules, and standalone through the makeNixvim function. To use the modules, just import the nixvim.homeModules.nixvim, nixvim.nixDarwinModules.nixvim, and nixvim.nixosModules.nixvim modules, depending on which system you're using.

For more detail, see the Usage section of our documentation.

Standalone Usage

Nixvim can also be used separately from NixOS, Home Manager, etc. To use Nixvim standalone, evaluate a Nixvim configuration and use its package output:

let
  nixvim = import (builtins.fetchTarball {
    # ...
  });
  configuration = nixvim.lib.evalNixvim {
    system = builtins.currentSystem;

    modules = [
      {
        colorschemes.gruvbox.enable = true;
      }
    ];
  };
in
configuration.config.build.package

The configuration also exposes a test derivation through configuration.config.build.test, which can be used from checks.

To get started with a standalone configuration, you can use the template by running the following command in an empty directory (recommended):

nix flake init --template github:nix-community/nixvim

Alternatively, you can create a minimal flake:

{
  description = "A very basic flake";

  inputs = {
    nixpkgs.follows = "nixvim/nixpkgs";
    nixvim.url = "github:nix-community/nixvim";
  };

  outputs =
    { nixpkgs, nixvim, ... }:
    let
      systems = [
        "x86_64-linux"
        "aarch64-linux"
        "aarch64-darwin"
      ];

      forAllSystems = nixpkgs.lib.genAttrs systems;
    in
    {
      packages = forAllSystems (
        system:
        let
          configuration = nixvim.lib.evalNixvim {
            inherit system;

            modules = [
              {
                colorschemes.gruvbox.enable = true;
              }
            ];
          };
        in
        {
          default = configuration.config.build.package;
        }
      );
    };
}

You can then run Neovim using nix run .# -- <file>. This can be useful for testing configuration changes.

For more information, see the Standalone Usage docs.

Documentation

Documentation is available on this project's GitHub Pages page: https://nix-community.github.io/nixvim

The stable documentation is also available at https://nix-community.github.io/nixvim/26.05.

If the option enableMan is set to true (by default it is), man pages will also be installed containing the same information, they can be viewed with man nixvim.

Plugins

After you have installed Nixvim, you will no doubt want to enable some plugins. Plugins are based on a modules system, similarly to NixOS and Home Manager.

So, to enable some supported plugin, all you have to do is enable its module:

{
  programs.nixvim = {
    plugins.lightline.enable = true;
  };
}

Of course, if that was everything, there wouldn't be much point to Nixvim, you'd just use a regular plugin manager. All options for supported plugins are exposed as options of that module. For now, there is no documentation yet, but there are detailed explanations in the source code. Detailed documentation for every module is planned.

Not all plugins will have modules, so you might still want to fetch some. This is not a problem, just use the extraPlugins option:

{
  programs.nixvim = {
    extraPlugins = with pkgs.vimPlugins; [
      vim-nix
    ];
  };
}

However, if you find yourself doing this a lot, please consider contributing or requesting a module!

Colorschemes

Colorschemes are provided within a different scope:

{
  programs.nixvim = {
    # Enable gruvbox
    colorschemes.gruvbox.enable = true;
  };
}

Just like with normal plugins, extra colorscheme options are provided as part of its module.

If your colorscheme isn't provided as a module, install it using extraPlugins and set it using the colorscheme option:

{
  programs.nixvim = {
    extraPlugins = [ pkgs.vimPlugins.gruvbox ];
    colorscheme = "gruvbox";
  };
}

All Nixvim supported plugins will, by default, use the main colorscheme you set, though this can be overridden on a per-plugin basis.

Options

Neovim has a lot of configuration options. You can find a list of them by doing :h option-list from within Neovim.

All of these are configurable from within Nixvim. All you have to do is set the opts attribute:

{
  programs.nixvim = {
    opts = {
      number = true;         # Show line numbers
      relativenumber = true; # Show relative line numbers

      shiftwidth = 2;        # Tab width should be 2
    };
  };
}

Please note that to, for example, disable numbers you would not set opts.nonumber to true, you'd set opts.number to false.

Key mappings

It is fully possible to define key mappings from within Nixvim. This is done using the keymaps attribute:

{
  programs.nixvim = {
    keymaps = [
      {
        key = ";";
        action = ":";
      }
      {
        mode = "n";
        key = "<leader>m";
        options.silent = true;
        action = "<cmd>!make<CR>";
      }
    ];
  };
}

This is equivalent to this vimscript:

noremap ; :
nnoremap <leader>m <silent> <cmd>make<CR>

This table describes all modes for the keymaps option. You can provide several modes to a single mapping by using a list of strings.

Each keymap can specify the following settings in the options attrs.

Globals

Sometimes you might want to define a global variable, for example to set the leader key. This is easy with the globals attribute:

{
  programs.nixvim = {
    globals.mapleader = ","; # Sets the leader key to comma
  };
}

Additional config

Sometimes Nixvim won't be able to provide for all your customization needs. In these cases, the extraConfigVim and extraConfigLua options are provided:

{
  programs.nixvim = {
    extraConfigLua = ''
      -- Print a little welcome message when Neovim is opened!
      print("Hello world!")
    '';
  };
}

If you feel like what you are doing manually should be supported in Nixvim, please open an issue.

Contributing

See CONTRIBUTING.md