DOCSEARCHbyAlgolia
Submit Docs

Nixvim Documentation

repository·main·Indexed 25 days ago

https://github.com/nix-community/nixvim

A Neovim configuration system built using Nix modules. Nixvim allows for declarative management of Neovim configurations, plugins, and colorschemes through Nix, while supporting raw Lua integration, custom LSP server modules, and flexible installation via Flakes, Home Manager, NixOS, or nix-darwin.

Tokens
7.9K
Snippets
30
Records
52
Agent score
83%

What's inside Nixvim

  1. Evaluate a Nixvim configuration standalone

    main

    When using Nixvim standalone (outside of NixOS, Home Manager, or nix-darwin), you must explicitly evaluate your configuration using nixvim.lib.evalNixvim. Unlike the module-based approaches, standalone options are available directly without a namespace prefix (e.g., use colorschemes.gruvbox.enable instead of programs.nixvim.colorschemes.gruvbox.enable).

    The resulting configuration object contains several key attributes:

    • config: The nested attribute set of all merged option values.
    • options: The nested attribute set of all option declarations.
    • type: A module system type.
    • extendModules: A function to extend the current configuration with additional modules.
    configuration = nixvim.lib.evalNixvim {
  inherit system;
  modules = [ ./config ];
};

  3. Install Nixvim via direct import

    main

    You can access Nixvim by performing a direct import using builtins.fetchGit. If you are not using the main branch, you can specify a specific branch using the ref attribute (e.g., ref = "nixos-26.05").

    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...

  4. Use a plugin packaged in nixpkgs but not implemented in Nixvim

    main

    If a plugin is available in nixpkgs but does not have a dedicated Nixvim module, you can manually register and configure it using extraPlugins and extraConfigLua.

    1. Add the plugin to extraPlugins using its path in pkgs.vimPlugins.
    2. Configure the plugin using Lua code in extraConfigLua.

  5. Use system provided binaries instead of Nixvim provided ones

    main

    Some plugins automatically install extra packages (like gcc via plugins.treesitter) which can interfere with system-provided binaries.

    To prevent a plugin from installing a specific package, look for a xxxPackage option (e.g., gccPackage) and set it to null.

  6. Run Lua code after a lazy-loaded plugin is configured

    main

    If you need to run extra Lua code after a plugin (or colorscheme) has been configured, do not override lazyLoad.settings.after. Instead, use the luaConfig.post hook. This ensures your code runs after the plugin setup regardless of whether it was lazy-loaded or not.

    {
  colorscheme = "catppuccin";
  colorschemes.catppuccin = {
    enable = true;
    lazyLoad.enable = true;
  
    # This code runs after catppuccin is setup,
    # regardless of whether it was lazy-loaded or not.
    luaConfig.post = ''
      -- At this point catppuccin is configured, so we can safely
      -- derive bufferline highlights or similar settings from it.
      require('lz.n').trigger_load("bufferline.nvim")
    ';
  };
  
  # Configure bufferline to load after catppuccin
  plugins.bufferline = {
    enable = true;
    settings.highlights.__raw = "require('catppuccin.special.bufferline').get_theme()";
    lazyLoad.settings.lazy = true; # Lazy load manually
  };
}

  7. Migrate from legacy Nixvim APIs to modern APIs

    main

    If you are using deprecated legacy functions, migrate to the modern evalNixvim based approach using the following mapping:

    Legacy APIModern equivalent
    makeNixvim module(evalNixvim { modules = [ module ]; }).config.build.package
    makeNixvimWithModule args(evalNixvim { ... }).config.build.package
    check.mkTestDerivationFromNixvimModule args(evalNixvim { ... }).config.build.test
    check.mkTestDerivationFromNvim { name = ""; inherit nvim; }nvim.config.build.test
    package.extend module((evalNixvim { ... }).extendModules { modules = [ module ]; }).config.build.package

  8. Lazy load colorschemes

    main

    Colorschemes can be lazy loaded using the lz-n provider. Nixvim automatically configures the colorscheme trigger to the name of the colorscheme so it loads when requested via the colorscheme option.

    {
  colorscheme = "catppuccin";
  colorschemes.catppuccin = {
    enable = true;
    lazyLoad.enable = true;
  };
}

  9. Integrate a standalone Nixvim flake into NixOS or Home Manager

    main

    If you have a standalone Nixvim configuration exported as the default package of a flake (e.g., nixvim-config), you can include it in your NixOS or Home Manager configurations via inputs.

    { inputs, system, ... }:
{
  # NixOS
  environment.systemPackages = [
    inputs.nixvim-config.packages.${system}.default
  ];

  # Home Manager
  home.packages = [
    inputs.nixvim-config.packages.${system}.default
  ];
}

  10. Use Nixvim as a module (NixOS, Home Manager, nix-darwin)

    main

    To use Nixvim as a module, you must import the appropriate module into your configuration system using imports = [ <nixvim_import> ]:

    • Home Manager: <nixvim>.homeModules.nixvim
    • NixOS: <nixvim>.nixosModules.nixvim
    • nix-darwin: <nixvim>.nixDarwinModules.nixvim

    Once imported, enable Nixvim with programs.nixvim.enable = true and configure options using the programs.nixvim.<path>.<to>.<option> syntax.

    Tip: Avoid deep nesting with programs.nixvim.imports To avoid prefixing every option with programs.nixvim, you can include your configuration files directly in programs.nixvim.imports. This provides access to Nixvim's extended lib and allows you to configure plugins directly (e.g., plugins.my-plugin.enable = true).

    # 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;
}