Official NixOS Wiki

Neovim: Difference between revisions

← Older edit
Kaarelkivisalu (talk | contribs)
1 edit
VisualWikitext
imported>Efskap
Setting default editor: use defaultEditor opt instead of env var
m Fix neovim command
 
(46 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]
}}


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


=== With Home Manager ===
<!--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.


[https://nixos.wiki/wiki/Home_Manager Home Manager] has a module for Neovim, which can be enabled via
== Installation == <!--T:3-->


<syntaxhighlight lang="nix">
==== Shell ==== <!--T:4-->
programs.neovim = {
  enable = true;
  extraConfig = ''
    set number relativenumber
  '';
};
</syntaxhighlight>
 
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-wide ===
 
If you do not use Home Manager, you can use the following code in your NixOS configuration:
 
<syntaxhighlight lang="nix">
programs.neovim = {
  enable = true;
  defaultEditor = true;
};
</syntaxhighlight>


You can also manually add Neovim to your packages. This should only be used if the two version above do not work for you.
<!--T:60-->
To temporarily use Neovim in a shell environment without modifying your system configuration, you can run:
</translate>


<syntaxhighlight lang="nix">
{{code|lang=bash|line=no|1=$ nix-shell -p neovim}}
environment.systemPackages = [ pkgs.neovim ];
</syntaxhighlight>


== Configuration ==
<translate>
<!--T:61-->
This makes the Neovim editor available in your current shell. You can then launch Neovim by typing <code>nvim</code>.


Neovim shares most of its configuration with Vim. See the [[Vim|Vim page]] for more details on the use of both.
==== System setup ==== <!--T:62-->


=== With Home Manager ===
<!--T:63-->
To install Neovim system-wide, making it available to all users, add the following to your configuration:
</translate>


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.
{{code|lang=nix|line=no|1=<translate><!--T:64--> # Example for /etc/nixos/configuration.nix</translate>
You can copy your old config or directly load your default Neovim config via:
environment.systemPackages = [
  pkgs.neovim
];


<syntaxhighlight lang="nix">
<translate><!--T:65--> # User-specific installation (in ~/.config/nixpkgs/home.nix)</translate>
programs.neovim.extraConfig = lib.fileContents ../path/to/your/init.vim;
home.packages = [
</syntaxhighlight>
  pkgs.neovim
];}}


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:
<translate>
<!--T:66-->
After rebuilding your system with <code>nixos-rebuild switch</code> or <code>home-manager switch</code>, Neovim will be installed and accessible.


<syntaxhighlight lang="nix">
== Configuration == <!--T:7-->
environment.variables.EDITOR = "nvim";
</syntaxhighlight>


The Home Manager module does also expose options to automatically add <code>vi</code> and <code>vim</code> aliases.
==== Basic ==== <!--T:8-->
To use them, add the following to your Home Manager configuration:
</translate>


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


==== Installing Plugins ====
<translate>
 
<!--T:40-->
Plugins can be installed using the <code>programs.neovim.plugins</code> option.
# Home Configuration
You can add only the plugin, or the plugin with its corresponding config:
</translate>
 
programs.neovim = {
<syntaxhighlight lang="nix">
   enable = true;
programs.neovim.plugins = [
   extraConfig = ''
   pkgs.vimPlugins.nvim-tree-lua
     set number relativenumber
   {
  '';
     plugin = pkgs.vimPlugins.vim-startify;
};}}
    config = "let g:startify_change_to_vcs_root = 0";
  }
];
</syntaxhighlight>


If you only add the plugin, you can add the configuration as described above.
<translate>
==== Advanced ==== <!--T:10-->
</translate>


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].
{{code|lang=nix|line=no|1=<translate>
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].
<!--T:41-->
 
# Global Configuration
=== System-wide ===
</translate>
 
The NixOS module does not have an <code>extraConfig</code> option as the Home Manager module does.
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].
 
The following example configures RC commands and enables the plugin <code>vim-nix</code> to support syntax highlighting for Nix files
 
<syntaxhighlight lang="nix">
programs.neovim = {
programs.neovim = {
   enable = true;
   enable = true;
  defaultEditor = true;
  viAlias = true;
  vimAlias = true;
   configure = {
   configure = {
     customRC = ''
     customRC = ''
Line 105: Line 109:
     '';
     '';
     packages.myVimPackage = with pkgs.vimPlugins; {
     packages.myVimPackage = with pkgs.vimPlugins; {
       start = [ vim-nix ];
       start = [ ctrlp ];
     };
     };
   };
   };
};
};
</syntaxhighlight>


To set Neovim as your default editor:
<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>
<!--T:12-->
== Tips and Tricks ==
{{expand}}
 
==== Package Variations ==== <!--T:15-->
 
<!--T:44-->
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.
 
<!--T:16-->
You can run the master version via the following command:
</translate>
 
{{code|lang=bash|line=no|1=$ nix run "github:nix-community/neovim-nightly-overlay"}}
 
<translate>
==== Plugin Management ==== <!--T:21-->
</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
    '';
  }
 
<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
    '';
  }


<syntaxhighlight lang="nix">
<translate>
programs.neovim = {
  <!--T:57-->
   defaultEditor = true;
# Installing grammars for tree-sitter
};
  # Option 1: Install all grammar packages
</syntaxhighlight>
  pkgs.vimPlugins.nvim-treesitter.withAllGrammars
 
  # Option 2: Install specific grammar packages
  # (pkgs.vimPlugins.nvim-treesitter.withPlugins (p: [ p.c p.java ]))
 
  <!--T:58-->
# Option 3: Installing grammars without Nix
   # Installing grammar packages through the built-in command can lead to errors.
  # The following Neovim command will install syntax highlighting for the C programming language: :TSInstall c
</translate>
];}}


Further, the NixOS module does also expose options to automatically add <code>vi</code> and <code>vim</code> aliases.
<translate>
To use them, add the following to your NixOS configuration:
==== Frameworks ==== <!--T:18-->


<syntaxhighlight lang="nix">
<!--T:45-->
programs.neovim = {
If you prefer not to configure your system manually, NixOS offers several predefined configurations and community-supported options. Here are a few of them:
  viAlias = true;
  vimAlias = true;
};
</syntaxhighlight>


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


=== Build Neovim using Nix ===
<!--T:46-->
* [https://astronvim.com/ AstroNvim]<ref>AstroNvim Team, "AstroNvim", AstroNvim Official Website, N/A, Accessed June 2025. https://astronvim.com/</ref>


You can also compile Neovim using nix. For this, the Neovim GitHub page has more information on this:
<!--T:47-->
[https://github.com/neovim/neovim/wiki/Building-Neovim#nixos--nix Neovim Guide].
* [https://nvchad.com/ NVChad]<ref>Siduck, "NvChad", NvChad Official Website, © 2025, Accessed June 2025. https://nvchad.com/</ref>
LazyVim, by default, will prevent loading plugins that are not managed by LazyVim. This includes all plugins installed via Nix. If you want to install plugins with both Nix and LazyVim, add the following to your LazyVim setup:


The Neovim repository also contains a flake.
</translate>
You can run the master version via the following command:
require("lazy").setup(lazyPackages, {
  performance = {
    reset_packpath = false, -- so that plugins outside of lazy can be loaded
  },
})
vim.cmd([[ packloadall]] ) -- load plugins outside of lazy


nix run "github:neovim/neovim?dir=contrib"
<translate>
[https://github.com/folke/lazy.nvim/issues/402#issuecomment-2084997594 Source]


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


=== Note on Lua plugins  ===
<!--T:68-->
You can create a custom neovim FHS wrapper
</translate>


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:
{{code|lang=nix|line=no|1=
{
  buildFHSEnv,
  writeShellScript,
  neovim,
}:
buildFHSEnv {
  name = "nvim-fhs";
  targetPkgs = pkgs: [ neovim ];


<syntaxhighlight lang="nix">
  runScript = writeShellScript "nvim-fhs.sh" ''
programs.neovim = {
     exec ${neovim}/bin/nvim "$@"
  plugins = [
   '';
    {
      plugin = pkgs.vimPlugins.nvim-colorizer-lua;
      config = ''
        packadd! nvim-colorizer.lua
        lua require 'colorizer'.setup()
      '';
     }
   ];
}
}
</syntaxhighlight>
}}
 
<!--T:FHS_WRAPPER_SOURCE-->
<translate>
<!--T:69-->
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].
 
<!--T:59-->
== Troubleshooting ==
{{expand}}
 
==== lua-language-server: Dynamically linked executable error ==== <!--T:70-->
 
<!--T:71-->
In your <code>~/.local/state/nvim/lsp.log</code>, you have the following error:
</translate>
 
{{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"}}
 
<!--T:LUA_LS_SO_REF-->
<translate>
<!--T:72-->
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>.
 
== See also == <!--T:73-->
 
<!--T:74-->
* [[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.


== See Also ==
== References == <!--T:27-->
* [[Vim]]
* [[Treesitter|Treesitter for Neovim]]


<!--T:75-->
[[Category:Applications]]
[[Category:Applications]]
[[Category:CLI Applications]]
[[Category:Text Editor]]
</translate>
Retrieved from "https://wiki.nixos.org/wiki/Neovim"