neovim-flake Manual

1. Default Configs
1.1. Tidal Cycles
1.2. Nix
1.3. Maximal
2. Custom Configuration
2.1. From Scratch
2.2. Extending Configurations
2.3. Running neovim
3. Language Support
A. Configuration Options
B. Release Notes
B.1. Release 0.1
B.1.1. Changelog


If you encounter problems or want to discuss neovim-flake then join the Matrix room If your problem is caused by a bug in neovim-flake then it should be reported on the neovim-flake issue tracker.

Chapter 1. Default Configs

While you can configure neovim-flake yourself using the builder, here are a few default configurations you can use.

1.1. Tidal Cycles

$ nix run github:jordanisaacs/neovim-flake#tidal file.tidal

Utilizing vim-tidal and mitchmindtree’s fantastic tidalcycles.nix start playing with tidal cycles in a single command.

In your tidal file, type a cycle e.g. d1 $ s "drum" and then press ctrl+enter. Super collider with superdirt, and a modified GHCI with tidal will start up and begin playing. Note, you need jack enabled on your system. If you are using pipewire, its as easy as setting services.pipewire.jack.enable = true.

1.2. Nix

$ nix run github:jordanisaacs/neovim-flake#nix test.nix

Enables all the of neovim plugins, with language support for specifically Nix. This lets you see what a fully configured neovim setup looks like without downloading a whole bunch of language servers and associated tools.

1.3. Maximal

$ nix shell github:jordanisaacs/neovim-flake#maximal test.nix

It is the same fully configured neovim as with the Nix config, but with every supported language enabled.


Running the maximal config will download a lot of packages as it is downloading language servers, formatters, and more.

Chapter 2. Custom Configuration

2.1. From Scratch

Custom configuration is done with the neovimConfiguration function. It takes in the configuration as a list of modules. The output of the configuration function is the configured neovim package. Additionally, information about the module is given in the package’s meta attributes. Once you have created a configuration from scratch, you can additionally use the extendConfiguration passthru function provided.

  meta.module.options = "The final module options";
  meta.module.config = "The final module configuration";
  passthru.extendConfiguration = "The function to extend configuration, see below";

The following is an example of a barebones vim configuration with the default theme enabled.

  inputs.neovim-flake.url = "github:jordanisaacs/neovim-flake";

  outputs = {nixpkgs, neovim-flake, ...}: let
    system = "x86_64-linux";
    pkgs = nixpkgs.legacyPackages.${system};
    configModule = {
      # Add any custom options (and feel free to upstream them!)
      # options = ...

      config.vim.theme.enable = true;

    customNeovim = neovim-flake.lib.neovimConfiguration {
      modules = [configModule];
      inherit pkgs;
  in {
    packages.${system}.neovim = customNeovim;

2.2. Extending Configurations

All of the default configurations provided by the flake are overrideable. Additionally, as noted above, the output package of the neovimConfiguration function also provides a passthru: extendConfiguration which you can use to extend configs. Thus, you can chain together configurations as seen below:

  inputs.neovim-flake.url = "github:jordanisaacs/neovim-flake";

  outputs = {
  }: let
    system = "x86_64-linux";
    pkgs = nixpkgs.legacyPackages.${system};
    lib = nixpkgs.lib;
    configModule = { = "dracula-nvim";
      config.vim.languages.nix.enable = false;

    configModule2 = { = lib.mkForce "catppuccin";
      config.vim.languages.nix.enable = lib.mkForce true;

    baseNeovim = neovim-flake.packages.${system}.maximal;
    neovimExtended = baseNeovim.extendConfiguration {modules = [configModule];};
    finalNeovim = neovimExtended.extendConfiguration {
      modules = [configModule2];
      inherit pkgs;
  in {
    packages.${system}.neovim = finalNeovim;

2.3. Running neovim

Once you have a configuration you like, you can run it with the following.

$ nix run .#neovim

Chapter 3. Language Support

Language specific support means there is a combination of language specific plugins, treesitter support, nvim-lspconfig language servers, and null-ls integration. This gets you capabilities ranging from autocompletion to formatting to diagnostics. The following languages have sections under the vim.languages attribute. See the configuration docs for details.

Adding support for more languages, and improving support for existing ones are great places where you can contribute with a PR.