Installation

You must use a nixpkgs version compatible with the Nixvim version you choose.

The main branch requires to use a very recent version of nixpkgs unstable. In order to guarantee the compatibility between Nixvim & nixpkgs it is recommended to always update both at the same time.

When using a stable version you must use the corresponding Nixvim branch, for example nixos-26.05 when using NixOS 26.05.

Failure to use the correct branch, or an old revision of nixpkgs will likely result in errors of the form vimPlugins.<name> attribute not found.

Nixvim can be used in four ways:

• As a NixOS module
• As a Home Manager module
• As a nix-darwin module
• As a standalone derivation

Nixvim is also available for nix flakes, or directly through an import.

Accessing nixvim

For a direct import you can add Nixvim to your configuration as follows:

let
  nixvim = import (builtins.fetchGit {
    url = "https://github.com/nix-community/nixvim";
    # When using a different channel you can use `ref = "nixos-<version>"` to set it here
  });
in
# configurations...

When using flakes you can simply add nixvim to the inputs:

{
  inputs.nixvim = {
    url = "github:nix-community/nixvim";
    # If using a stable channel you can use `url = "github:nix-community/nixvim/nixos-<version>"`
  };

  # outputs...
}

We recommend against using inputs.nixpkgs.follows = "nixpkgs"; on the nixvim input as we test Nixvim against our Nixpkgs revision. When you use follows you opt out of guarantees provided by these tests. If you choose to use it anyway, removing follows should be one of the first debugging steps when encountering issues.

Usage

Nixvim can be used standalone or as a module for NixOS, Home Manager, or nix-darwin.

When used standalone, a custom Nixvim derivation is produced that can be used like any other package.

When used as a module, Nixvim can be enabled though programs.nixvim.enable.

Usage as a module (NixOS, Home Manager, nix-darwin)

When using Nixvim as a module you must import the Nixvim module into your module system. The three imports are:

• <nixvim>.homeModules.nixvim
• <nixvim>.nixosModules.nixvim
• <nixvim>.nixDarwinModules.nixvim

<nixvim> refers to the way to access Nixvim, depending on how you fetched Nixvim as described in the previous section.

The imports can be added as a imports = [ <nixvim_import> ] in a configuration file.

You will then be able to enable Nixvim through programs.nixvim.enable = true, and configure the options as programs.nixvim.<path>.<to>.<option> = <value>.

Tip

Use programs.nixvim.imports to include modules configuring Nixvim so you get Nixvim’s extended lib in the lib module argument and you don’t have to prefix everything with programs.nixvim.

# home-config.nix
{
  # Imported modules are scoped within the `programs.nixvim` submodule
  programs.nixvim.imports = [ ./nixvim.nix ];
}

# nixvim.nix
{ lib, ... }:
{
  # You can use lib.nixvim in your config
  fooOption = lib.nixvim.mkRaw "print('hello')";

  # Configure Nixvim without prefixing with `plugins.nixvim`
  plugins.my-plugin.enable = true;
}

When you use Nixvim as a module, an additional module argument is passed on allowing you to peek through the configuration with hmConfig, nixosConfig, and darwinConfig for Home Manager, NixOS, and nix-darwin respectively. This is useful if you use Nixvim both as part of an environment and standalone.

For more platform-specific options and information, see Nixvim Platforms.

Standalone usage

When using Nixvim standalone, start by evaluating a Nixvim configuration:

configuration = nixvim.lib.evalNixvim {
  inherit system;
  modules = [ ./config ];
};

The resulting configuration exposes several useful outputs:

• configuration.config.build.package: builds the Neovim package. The package output can be used like any other package.
• configuration.config.build.test: builds a test derivation for the configuration. The derivation will fail to build if the test fails.

For a complete example, see our standalone flake template.

For more information, including extending configurations and accessing configuration values, see Standalone Usage.

Important

If you are using the legacy standalone APIs (makeNixvim, makeNixvimWithModule, etc.), see Legacy Standalone Functions.