NixOS Wiki

Neovim: Difference between revisions

← Older edit
VisualWikitext
imported>Onny
Add example system configuration
U32 (talk | contribs)
1 edit
mNo edit summary
 
(45 intermediate revisions by 19 users not shown)
Line 1: Line 1:
[https://neovim.io Neovim] is a fork of [[Vim]] aiming to improve the codebase, allowing for easier implementation of APIs, improved user experience and plugin implementation.  
<languages/>
{{infobox application
  |name=Neovim
  |image=Neovim-mark.svg
  |type=Text Editor
  |developer=Neovim Core Team & Community
  |firstRelease=November 1, 2015
  |latestRelease=Nvim 0.11.2 (May 30, 2025)
  |status=Active
  |license=[https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] (with parts under Vim license)
  |os=Cross-platform (Linux, macOS, Windows)
  |platform=Desktop
  |programmingLanguage=C, Lua, Vim Script
  |website=[https://neovim.io/ neovim.io]
  |github=neovim/neovim
  |bugTracker=[https://github.com/neovim/neovim/issues GitHub Issues]
  |documentation=[https://neovim.io/doc/ Official Documentation]
}}
<translate>
<!--T:1-->
:''See also: [[Vim]]''
[https://neovim.io/ Neovim]<ref>Neovim Team, "Home - Neovim", Neovim Official Website, Last updated March 2025, Accessed June 2025. https://neovim.io/</ref> is a highly extensible and open source text editor that aims to improve upon and modernize the popular [[Vim]]<ref>NixOS Wiki Community, "Vim", NixOS Wiki, Last edited 24 February 2025, Accessed June 2025. https://wiki.nixos.org/wiki/Vim</ref> editor. It's designed to be a drop-in replacement for Vim, maintaining compatibility with most Vim plugins and configurations while offering additional features and improvements. Neovim focuses on extensibility, usability, and performance.


== Installation ==
<!--T:2-->
It introduces a powerful plugin architecture that allows for asynchronous plugin execution, which can significantly improve performance for certain operations. It also includes a built-in terminal emulator, allowing users to run shell commands directly within the editor. The project emphasizes code quality and maintainability, with a clean, well-documented codebase that makes it easier for developers to contribute.


=== With Home Manager ===
== Installation == <!--T:3-->


[https://nixos.wiki/wiki/Home_Manager Home Manager] has a module for Neovim, which can be enabled via
==== Shell ====


  programs.neovim = {
To temporarily use Neovim in a shell environment without modifying your system configuration, you can run:
    enable = true;
{{code|lang=bash|line=no|1=$ nix-shell -p neovim}}
    extraConfig = <nowiki>''</nowiki>
This makes the Neovim editor available in your current shell. You can then launch Neovim by typing <code>neovim</code>.
      set number relativenumber
    <nowiki>''</nowiki>;
  };


More information about the module can be found here: [https://nix-community.github.io/home-manager/options.html#opt-programs.neovim.enable Home Manager Manual].
==== System setup ====


=== System-wide ===
To install Neovim system-wide, making it available to all users, add the following to your configuration:
{{code|lang=nix|line=no|1=# Example for /etc/nixos/configuration.nix
environment.systemPackages = [
  pkgs.neovim
];


If you do not use Home Manager, you can use the following code in your NixOS configuration:
# User-specific installation (in ~/.config/nixpkgs/home.nix)
home.packages = [
  pkgs.neovim
];}}
After rebuilding your system with <code>nixos-rebuild switch</code> or <code>home-manager switch</code>, Neovim will be installed and accessible.


  programs.neovim = {
    enable = true;
    defaultEditor = true;
  };


You can also manually add Neovim to your packages. This should only be used if the two version above do not work for you.
== Configuration == <!--T:7-->


  environment.systemPackages = [ pkgs.neovim ];
==== Basic ==== <!--T:8-->


== Configuration ==
</translate>
{{code|lang=nix|line=no|1=<translate>
<!--T:39-->
# Global Configuration
</translate>
programs.neovim = {
  enable = true;
  defaultEditor = true;
};


Neovim shares most of its configuration with Vim. See the [[Vim|Vim page]] for more details on the use of both.
<translate>
<!--T:40-->
# Home Configuration
</translate>
programs.neovim = {
  enable = true;
  extraConfig = ''
    set number relativenumber
  '';
};}}
<translate>


=== With Home Manager ===
==== Advanced ==== <!--T:10-->


The Home Manager module does not expose many configuration options. Therefore, the easiest way to get started is to use the [https://nix-community.github.io/home-manager/options.html#opt-programs.neovim.extraConfig extraConfig] option.
</translate>
You can copy your old config or directly load your default Neovim config via:
{{code|lang=nix|line=no|1=<translate>
<!--T:41-->
# Global Configuration
</translate>
programs.neovim = {
  enable = true;
  defaultEditor = true;
  viAlias = true;
  vimAlias = true;
  configure = {
    customRC = ''
      set number
      set cc=80
      set list
      set listchars=tab:→\ ,space:·,nbsp:␣,trail:•,eol:¶,precedes:«,extends:»
      if &diff
        colorscheme blue
      endif
    '';
    packages.myVimPackage = with pkgs.vimPlugins; {
      start = [ ctrlp ];
    };
  };
};


  programs.neovim.extraConfig = lib.fileContents ../path/to/your/init.vim;
<translate>
<!--T:42-->
# Home Configuration
# You have to add the line below to set it as the default editor:
</translate>
environment.variables.EDITOR = "nvim";}}
<translate>


To use Neovim as your default editor, you can set the <code>EDITOR</code> [https://search.nixos.org/options?show=environment.variables&type=packages&query=environment.variables environmental variable] to "nvim" by adding the following to your NixOS configuration:
== Tips and Tricks == <!--T:12-->
{{expand}}


  environment.variables.EDITOR = "nvim";
==== Package Variations ==== <!--T:15-->


The Home Manager module does also expose options to automatically add <code>vi</code> and <code>vim</code> aliases.
Have a look at the [https://github.com/nix-community/neovim-nightly-overlay Neovim Nightly Overlay]<ref>Nix Community, "neovim-nightly-overlay", GitHub, Last updated June 2025, Accessed June 2025. https://github.com/nix-community/neovim-nightly-overlay</ref> to install the most recent current nightly version of Neovim.
To use them, add the following to your Home Manager configuration:
You can run the master version via the following command:
{{code|lang=bash|line=no|1=$ nix run "github:nix-community/neovim-nightly-overlay"}}


   programs.neovim = {
==== Plugin Management ==== <!--T:21-->
     viAlias = true;
 
     vimAlias = true;
</translate>
   };
{{code|lang=nix|line=no|1=plugins = [
<translate>
  <!--T:49-->
# Example Plugin: nvim-tree-lua
</translate>
   pkgs.vimPlugins.nvim-tree-lua
 
<translate>
  <!--T:50-->
# Example Plugin: vim-startify with configuration
</translate>
  {
    plugin = pkgs.vimPlugins.vim-startify;
    config = "let g:startify_change_to_vcs_root = 0";
  }
 
<translate>
  <!--T:51-->
# Example Plugin: nvim-colorizer-lua with Lua config
  # Due to how the runtimepath for Lua modules is processed, your configuration may require
  # packadd! plugin-name to require a module. A home-manager example:
</translate>
  {
     plugin = pkgs.vimPlugins.nvim-colorizer-lua;
     config = ''
      packadd! nvim-colorizer.lua
      lua << END
        require 'colorizer'.setup {
          '*';<translate> <!--T:52--> -- Highlight all files, but customize some others.</translate>
          '!vim';<translate> <!--T:53--> -- Exclude vim from highlighting.</translate>
        }
      END
    '';
   }


==== Installing Plugins ====
<translate>
  <!--T:54-->
# Example Plugin: nvim-treesitter with Lua config
</translate>
  {
    plugin = pkgs.vimPlugins.nvim-treesitter;
    config = ''
      packadd! nvim-treesitter
      lua <<EOF
        require'nvim-treesitter.configs'.setup {
          highlight = {
            enable = true,              <translate><!--T:55--> -- false will disable the whole extension</translate>
            disable = {},              <translate><!--T:56--> -- list of languages that will be disabled</translate>
          },
          incremental_selection = {
            enable = true,
            keymaps = {
              init_selection = "gnn",
              node_incremental = "grn",
              scope_incremental = "grc",
              node_decremental = "grm",
            },
          },
          textobjects = {
            select = {
              enable = true,
              lookahead = true,
              keymaps = {
                ["af"] = "@function.outer",
                ["if"] = "@function.inner",
                ["ac"] = "@class.outer",
                ["ic"] = "@class.inner",
              },
            },
          },
        }
      EOF
    '';
  }


Plugins can be installed using the <code>programs.neovim.plugins</code> option.
<translate>
You can add only the plugin, or the plugin with its corresponding config:
  <!--T:57-->
# Installing grammars for tree-sitter
  # Option 1: Install all grammar packages
  pkgs.vimPlugins.nvim-treesitter.withAllGrammars
 
  # Option 2: Install specific grammar packages
  # (pkgs.vimPlugins.nvim-treesitter.withPlugins (p: [ p.c p.java ]))


   programs.neovim.plugins = [
   <!--T:58-->
    pkgs.vimPlugins.nvim-tree-lua
# Option 3: Installing grammars without Nix
    {
  # Installing grammar packages through the built-in command can lead to errors.
      plugin = pkgs.vimPlugins.vim-startify;
  # The following Neovim command will install syntax highlighting for the C programming language: :TSInstall c
      config = "let g:startify_change_to_vcs_root = 0";
</translate>
    }
];}}
  ];
<translate>


If you only add the plugin, you can add the configuration as described above.
==== Frameworks ==== <!--T:18-->


An index of official packages can be found in on [https://search.nixos.org/packages?from=0&size=50&sort=relevance&type=packages&query=vimPlugins search.nixos.org].
<!--T:45-->
In addition to the official packages, there are several user maintained repositories, such as [https://github.com/m15a/nixpkgs-vim-extra-plugins vim-extra-plugins] or [https://github.com/NixNeovim/NixNeovimPlugins NixNeovimPlugins].
If you prefer not to configure your system manually, NixOS offers several predefined configurations and community-supported options. Here are a few of them:


=== System-wide ===
<!--T:19-->
* [https://www.lazyvim.org/ LazyVim]<ref>LazyVim Team, "Getting Started", LazyVim Official Website, © 2025, Accessed June 2025. https://www.lazyvim.org/</ref>


The NixOS module does not have an <code>extraConfig</code> option as the Home Manager module does.
<!--T:46-->
Instead, you can use the <code>programs.neovim.configure</code> option as described [https://search.nixos.org/options?show=programs.neovim.configure&type=packages&query=neovim here].
* [https://astronvim.com/ AstroNvim]<ref>AstroNvim Team, "AstroNvim", AstroNvim Official Website, N/A, Accessed June 2025. https://astronvim.com/</ref>


The following example configures RC commands and enables the plugin <code>vim-nix</code> to support syntax highlighting for Nix files
<!--T:47-->
* [https://nvchad.com/ NVChad]<ref>Siduck, "NvChad", NvChad Official Website, © 2025, Accessed June 2025. https://nvchad.com/</ref>


  programs.neovim = {
<!--T:48--> ==== FHS wrapper ====
    enable = true;
    configure = {
      customRC = ''
        set number
        set cc=80
        set list
        set listchars=tab:→\ ,space:·,nbsp:␣,trail:•,eol:¶,precedes:«,extends:»
        if &diff
          colorscheme blue
        endif
      '';
      packages.myVimPackage = with pkgs.vimPlugins; {
        start = [ vim-nix ];
      };
    };
  };


Similarly to the Home Manager module, to set Neovim as your default editor you have to set the <code>EDITOR</code> environment variable like this:
You can create a custom neovim FHS wrapper
{{code|lang=nix|line=no|1=
{
  buildFHSEnv,
  writeShellScript,
  neovim,
}:
buildFHSEnv {
  name = "nvim-fhs";
  targetPkgs = pkgs: [ neovim ];


   environment.variables.EDITOR = "nvim";
   runScript = writeShellScript "nvim-fhs.sh" ''
    exec ${neovim}/bin/nvim "$@"
  '';
}
}}


Further, the NixOS module does also expose options to automatically add <code>vi</code> and <code>vim</code> aliases.
<!--T:FHS_WRAPPER_SOURCE-->
To use them, add the following to your NixOS configuration:
This FHS wrapper example is based on a contribution to nixpkgs<ref name="nixpkgs-pr-334032">NixOS, "Feature: Custom Neovim FHS Wrapper" (Pull Request #334032), GitHub, 2025, Accessed June 2025. https://github.com/NixOS/nixpkgs/pull/334032</ref>.
For an extended configuration that includes setting up `mason.nvim` with a similar FHS environment, see this [https://github.com/NixOS/nixpkgs/issues/281219#issuecomment-2284713258 NixOS/nixpkgs issue comment].


  programs.neovim = {
== Troubleshooting == <!--T:59-->
    viAlias = true;
{{expand}}
    vimAlias = true;
  };


== Build Neovim using Nix ==
==== lua-language-server: Dynamically linked executable error ====


You can also compile Neovim using nix. For this, the Neovim GitHub page has more information on this:
In your <code>~/.local/state/nvim/lsp.log</code>, you have the following error:
[https://github.com/neovim/neovim/wiki/Building-Neovim#nixos--nix Neovim Guide].


The Neovim repository also contains a flake.
{{code|lang=text|line=no|1=[ERROR][2025-06-07 23:13:15] ...p/_transport.lua:36 "rpc" "lua-language-server" "stderr" "Could not start dynamically linked executable: /home/incogshift/.local/share/nvim/mason/packages/lua-language-server/libexec/bin/lua-language-server\nNixOS cannot run dynamically linked executables intended for generic\nlinux environments out of the box. For more information, see:\nhttps://nix.dev/permalink/stub-ld\n"}}
You can run the master version via the following command:


nix run "github:neovim/neovim?dir=contrib"
<!--T:LUA_LS_SO_REF-->
A solution for this issue can be found on Stack Overflow<ref name="so-lua-ls-dynlink">Stack Overflow Contributor, "Answer to 'Could not start dynamically linked executable... on NixOS'", Stack Overflow, 2025, Accessed June 2025. https://stackoverflow.com/a/78215911/27134695</ref>.


Finally, there is a [https://github.com/nix-community/neovim-nightly-overlay Neovim Nightly Overlay].
== References == <!--T:27-->


== Note on Lua plugins  ==
== See also ==


Due to how the `runtimepath` for Lua modules is [https://github.com/nanotee/nvim-lua-guide#a-note-about-packages processed], your configuration may require <code>packadd! plugin-name</code> to require a module. A home-manager example:
* [[Home Manager]] – For declarative Neovim configuration at the user level: [https://nix-community.github.io/home-manager/options.html#opt-programs.neovim.enable Neovim module in Home Manager]
* [https://neovim.io/doc/ Official Documentation] – Official Neovim documentation.
* [https://search.nixos.org/options?channel=unstable&query=programs.neovim NixOS options for Neovim] – System-level Neovim configuration.
* [https://discourse.nixos.org/search?q=neovim Neovim discussions on NixOS Discourse] – Community tips, troubleshooting, and use cases.
* [https://github.com/nix-community/neovim-overlay Neovim Overlay on Nixpkgs] – For nightly builds and additional Neovim packages.


  programs.neovim = {
== References ==
    plugins = [
      {
        plugin = nvim-colorizer-lua
        config = <nowiki>''</nowiki>
          packadd! nvim-colorizer.lua
          lua require 'colorizer'.setup()
        <nowiki>''</nowiki>;
      }
    ];
  }


== See Also ==
</translate>
* [[Vim]]
* [[Treesitter|Treesitter for Neovim]]


[[Category:Applications]]
[[Category:Applications]]
[[Category:CLI Applications]]
[[Category:Text Editor]]
Retrieved from "https://wiki.nixos.org/wiki/Neovim"