Repository files navigation

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

NixVim is aNeovim distribution built aroundNix modules. It is distributed as a Nix flake, andconfigured through Nix, all while leaving room for your plugins and your vimrc.

Here is a simple configuration that uses catppuccin as the colorscheme and uses thelualine 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 usecatppuccin as the colorscheme, no extra configuration required!

Check outthis list of real world nixvim configs!

When you build the module (probably using home-manager), it will install allyour plugins and generate a lua config for NeoVim with all the optionsspecified. Because it uses lua, this ensures that your configuration will loadas fast as possible.

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

Most plugins have asettings option, which acceptsany nix attribute setand translate it into a lua table. This is then passed to the plugin'ssetupfunction. In practice this means if a plugin has asettings option, any pluginoption can be configured, even if we don't explicitly have a corresponding nixoption.

If you just want to add additional lines of lua to yourinit.lua, you can useextraConfigLua,extraConfigLuaPre, andextraConfigLuaPost.

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,}

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

For more detail, see theInstallation section of our documentation.

{pkgs,lib, ...}:letnixvim=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-24.11";});in{imports=[# For home-managernixvim.homeManagerModules.nixvim# For NixOSnixvim.nixosModules.nixvim# For nix-darwinnixvim.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-24.11";inputs.nixpkgs.follows="nixpkgs";};}

NixVim can be used in four ways: through the home-manager, nix-darwin, NixOS modules,and standalone through themakeNixvim function. To use the modules, just import thenixvim.homeManagerModules.nixvim,nixvim.nixDarwinModules.nixvim, andnixvim.nixosModules.nixvim modules, depending on which systemyou're using.

For more detail, see theUsage section of our documentation.

If you want to use it standalone, you can use themakeNixvim function:

{pkgs,nixvim, ...}:{environment.systemPackages=[(nixvim.legacyPackages."${pkgs.stdenv.hostPlatform.system}".makeNixvim{colorschemes.gruvbox.enable=true;})];}

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, if you want a minimal flake to allow building a custom neovim youcan use the following:

{description="A very basic flake";inputs.nixvim.url="github:nix-community/nixvim";outputs={self,nixvim,flake-parts,} @inputs:letconfig={colorschemes.gruvbox.enable=true;};inflake-parts.lib.mkFlake{inheritinputs;}{systems=["aarch64-darwin""aarch64-linux""x86_64-darwin""x86_64-linux"];perSystem={pkgs,system,        ...}:letnixvim'=nixvim.legacyPackages."${system}";nvim=nixvim'.makeNixvimconfig;in{packages={inheritnvim;default=nvim;};};};}

You can then run neovim usingnix run .# -- <file>. This can be useful to testconfig changes easily.

You may want more control over the nixvim modules, like:

• Splitting your configuration in multiple files
• Adding custom nix modules to enhance nixvim
• Change the nixpkgs used by nixvim

In this case, you can use themakeNixvimWithModule function.

It takes a set with the following keys:

• pkgs: The nixpkgs to use (defaults to the nixpkgs pointed at by the nixvim flake)
• module: The nix module definition used to extend nixvim.This is useful to pass additional module machinery likeoptions orimports.
• extraSpecialArgs: Extra arguments to pass to the modules when using functions.Can beself in a flake, for example.

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

You can also use nixvim to define an instance which will only be available inside a NixdevShell:

letnvim=nixvim.legacyPackages.x86_64-linux.makeNixvim{plugins.lsp.enable=true;};inpkgs.mkShell{buildInputs=[nvim];};

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

The stable documentation is also available athttps://nix-community.github.io/nixvim/24.11.

If the optionenableMan is set totrue (by default it is), man pages will alsobe installed containing the same information, they can be viewed withman nixvim.

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'djust use a regular plugin manager. All options for supported plugins are exposedas options of that module. For now, there is no documentation yet, but there aredetailed explanations in the source code. Detailed documentation for everymodule is planned.

Not all plugins will have modules, so you might still want to fetch some. Thisis not a problem, just use theextraPlugins option:

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

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

Colorschemes are provided within a different scope:

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

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

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

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

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

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 theopts attribute:

{programs.nixvim={opts={number=true;# Show line numbersrelativenumber=true;# Show relative line numbersshiftwidth=2;# Tab width should be 2};};}

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

It is fully possible to define key mappings from within NixVim. This is doneusing thekeymaps 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 thekeymaps option.You can provide several modes to a single mapping by using a list of strings.

Each keymap can specify the following settings in theoptions attrs.

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

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

Sometimes NixVim won't be able to provide for all your customization needs.In these cases, theextraConfigVim andextraConfigLua options areprovided:

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

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

SeeCONTRIBUTING.md