{"id":13494677,"url":"https://github.com/nix-community/nixvim","last_synced_at":"2025-05-14T01:07:40.245Z","repository":{"id":41265271,"uuid":"325421844","full_name":"nix-community/nixvim","owner":"nix-community","description":"Configure Neovim with Nix! [maintainers=@GaetanLepage, @traxys, @mattsturgeon, @khaneliman]","archived":false,"fork":false,"pushed_at":"2025-05-10T16:28:44.000Z","size":7097,"stargazers_count":2157,"open_issues_count":141,"forks_count":327,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-05-10T17:32:01.632Z","etag":null,"topics":["neovim","nix","nix-community-buildbot","nixos","nixos-module","vim"],"latest_commit_sha":null,"homepage":"https://nix-community.github.io/nixvim","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nix-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"open_collective":"nix-community"}},"created_at":"2020-12-30T01:08:04.000Z","updated_at":"2025-05-10T16:28:47.000Z","dependencies_parsed_at":"2023-12-27T21:47:01.822Z","dependency_job_id":"a01328c3-96cc-494e-9bb7-e234e168c6df","html_url":"https://github.com/nix-community/nixvim","commit_stats":{"total_commits":2687,"total_committers":203,"mean_commits":"13.236453201970443","dds":0.6505396352809825,"last_synced_commit":"3285bbda0aa0151c3b1914758e6950dfb554962f"},"previous_names":["nix-community/nixvim","pta2002/nixvim"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnixvim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnixvim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnixvim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nix-community%2Fnixvim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nix-community","download_url":"https://codeload.github.com/nix-community/nixvim/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253871712,"owners_count":21976741,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["neovim","nix","nix-community-buildbot","nixos","nixos-module","vim"],"created_at":"2024-07-31T19:01:27.113Z","updated_at":"2025-05-14T01:07:40.222Z","avatar_url":"https://github.com/nix-community.png","language":"Nix","funding_links":["https://opencollective.com/nix-community"],"categories":["Nix","Editors and IDEs","neovim","NixOS Modules"],"sub_categories":["Zig"],"readme":"\u003ch2 align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003cimg src=\"assets/nixvim_logo.svg\" width=\"25%\" /\u003e\n  \u003c/picture\u003e\n\n  \u003ca href=\"https://nix-community.github.io/nixvim\"\u003eDocumentation\u003c/a\u003e |\n  \u003ca href=\"https://matrix.to/#/#nixvim:matrix.org\"\u003eChat\u003c/a\u003e\n\u003c/h2\u003e\n\n# NixVim - A Neovim configuration system for nix\n\n- [Quick set up tutorial](https://www.youtube.com/watch?v=b641h63lqy0) (by [@Vimjoyer](https://www.youtube.com/@vimjoyer))\n- [Nixvim: How to configure Neovim with the power of Nix](https://www.youtube.com/watch?v=GOe0C7Qtypk) (NeovimConf 2023 talk by [@GaetanLepage](https://glepage.com/))\n\n\u003c!-- START DOCS --\u003e\n\n## What is it?\nNixVim is a [Neovim](https://neovim.io) distribution built around\n[Nix](https://nixos.org) modules. It is distributed as a Nix flake, and\nconfigured through Nix, all while leaving room for your plugins and your vimrc.\n\n## What does it look like?\nHere is a simple configuration that uses catppuccin as the colorscheme and uses the\nlualine plugin:\n\n```nix\n{\n  programs.nixvim = {\n    enable = true;\n\n    colorschemes.catppuccin.enable = true;\n    plugins.lualine.enable = true;\n  };\n}\n```\n\nWhen we do this, lualine will be set up to a sensible default, and will use\ncatppuccin as the colorscheme, no extra configuration required!\n\nCheck out [this list of real world nixvim configs](https://nix-community.github.io/nixvim/user-guide/config-examples.html)!\n\n\u003c!-- STOP DOCS --\u003e\n\n## How does it work?\nWhen you build the module (probably using home-manager), it will install all\nyour plugins and generate a lua config for NeoVim with all the options\nspecified. Because it uses lua, this ensures that your configuration will load\nas fast as possible.\n\nSince everything is disabled by default, it will be as snappy as you want it to\nbe.\n\n### Plugin settings\nMost plugins have a `settings` option, which accepts _any_ nix attribute set\nand translate it into a lua table. This is then passed to the plugin's `setup`\nfunction. In practice this means if a plugin has a `settings` option, any plugin\noption can be configured, even if we don't explicitly have a corresponding nix\noption.\n\n### Raw lua\nIf you just want to add additional lines of lua to your `init.lua`, you can use\n`extraConfigLua`, `extraConfigLuaPre`, and `extraConfigLuaPost`.\n\nIf you want to assign lua code to an option that'd normally accept another type\n(string, int, etc), you can use nixvim's \"raw type\", `{ __raw = \"lua code\"; }`.\n\n\u003cdetails\u003e\n  \u003csummary\u003eExample\u003c/summary\u003e\n\nThis nix code:\n```nix\n{\n  some_option.__raw = \"function() print('hello, world!') end\";\n}\n```\nWill produce the following lua:\n```lua\n{\n  ['some_option'] = function() print('hello, world!') end,\n}\n```\n\n\u003c/details\u003e\n\n## Support/Questions\nIf you have any question, please use the [discussions page](https://github.com/nix-community/nixvim/discussions/categories/q-a)! Alternatively, join the Matrix channel at [#nixvim:matrix.org](https://matrix.to/#/#nixvim:matrix.org)!\n\n## Installation\n\n\u003e [!WARNING]\n\u003e NixVim needs to be installed with a compatible nixpkgs version.\n\u003e This means that the `main` branch of NixVim requires to be installed with `nixpkgs-unstable`.\n\u003e\n\u003e If you want to use NixVim with nixpkgs 24.11 you should use the `nixos-24.11` branch.\n\nFor more detail, see the [Installation](https://nix-community.github.io/nixvim) section of our documentation.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eWithout flakes\u003c/strong\u003e\u003c/summary\u003e\n\nNixVim now ships with `flake-compat`, which makes it usable from any system.\n\nTo install it, edit your home-manager (or NixOS) configuration:\n\n```nix\n{ pkgs, lib, ... }:\nlet\n  nixvim = import (builtins.fetchGit {\n    url = \"https://github.com/nix-community/nixvim\";\n    # If you are not running an unstable channel of nixpkgs, select the corresponding branch of nixvim.\n    # ref = \"nixos-24.11\";\n  });\nin\n{\n  imports = [\n    # For home-manager\n    nixvim.homeManagerModules.nixvim\n    # For NixOS\n    nixvim.nixosModules.nixvim\n    # For nix-darwin\n    nixvim.nixDarwinModules.nixvim\n  ];\n\n  programs.nixvim.enable = true;\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eUsing flakes\u003c/strong\u003e\u003c/summary\u003e\n\nThis is the recommended method if you are already using flakes to manage your\nsystem. To enable flakes, add this to `/etc/nixos/configuration.nix`\n\n```nix\n{ pkgs, lib, ... }:\n{\n  nix = {\n    settings.experimental-features = [ \"nix-command\" \"flakes\" ];\n  };\n}\n```\n\nNow, you need to import the module. If your system is already configured using\nflakes, just add the nixvim input:\n\n```nix\n{\n  # ...\n  inputs.nixvim = {\n    url = \"github:nix-community/nixvim\";\n    # If you are not running an unstable channel of nixpkgs, select the corresponding branch of nixvim.\n    # url = \"github:nix-community/nixvim/nixos-24.11\";\n\n    inputs.nixpkgs.follows = \"nixpkgs\";\n  };\n}\n```\n\nYou can now access the module using `inputs.nixvim.homeManagerModules.nixvim`,\nfor a home-manager installation, `inputs.nixvim.nixosModules.nixvim`, for NixOS,\nand `inputs.nixvim.nixDarwinModules.nixvim` for nix-darwin.\n\n\u003c/details\u003e\n\n## Usage\nNixVim can be used in four ways: through the home-manager, nix-darwin, NixOS modules,\nand standalone through the `makeNixvim` function. To use the modules, just import the\n`nixvim.homeManagerModules.nixvim`, `nixvim.nixDarwinModules.nixvim`, and\n`nixvim.nixosModules.nixvim` modules, depending on which system\nyou're using.\n\nFor more detail, see the [Usage](https://nix-community.github.io/nixvim/user-guide/install.html#usage) section of our documentation.\n\n### Standalone Usage\n\nIf you want to use it standalone, you can use the `makeNixvim` function:\n\n```nix\n{ pkgs, nixvim, ... }: {\n  environment.systemPackages = [\n    (nixvim.legacyPackages.\"${pkgs.stdenv.hostPlatform.system}\".makeNixvim {\n      colorschemes.gruvbox.enable = true;\n    })\n  ];\n}\n```\n\nTo get started with a standalone configuration, you can use the template by running the following command in an empty directory (recommended):\n\n```\nnix flake init --template github:nix-community/nixvim\n```\n\nAlternatively, if you want a minimal flake to allow building a custom neovim you\ncan use the following:\n\n\u003cdetails\u003e\n  \u003csummary\u003eMinimal flake configuration\u003c/summary\u003e\n\n```nix\n{\n  description = \"A very basic flake\";\n\n  inputs = {\n    nixpkgs.follows = \"nixvim/nixpkgs\";\n    nixvim.url = \"github:nix-community/nixvim\";\n  };\n\n  outputs =\n    { nixpkgs, nixvim, ... }:\n    let\n      config = {\n        colorschemes.gruvbox.enable = true;\n      };\n\n      systems = [\n        \"x86_64-linux\"\n        \"aarch64-linux\"\n        \"x86_64-darwin\"\n        \"aarch64-darwin\"\n      ];\n\n      forAllSystems = nixpkgs.lib.genAttrs systems;\n    in\n    {\n      packages = forAllSystems (\n        system:\n        let\n          nixvim' = nixvim.legacyPackages.${system};\n          nvim = nixvim'.makeNixvim config;\n        in\n        {\n          inherit nvim;\n          default = nvim;\n        }\n      );\n    };\n}\n```\n\u003c/details\u003e\n\nYou can then run neovim using `nix run .# -- \u003cfile\u003e`. This can be useful to test\nconfig changes easily.\n\n### Advanced Usage\n\nYou may want more control over the nixvim modules, like:\n\n- Splitting your configuration in multiple files\n- Adding custom nix modules to enhance nixvim\n- Change the nixpkgs used by nixvim\n\nIn this case, you can use the `makeNixvimWithModule` function.\n\nIt takes a set with the following keys:\n- `pkgs`: The nixpkgs to use (defaults to the nixpkgs pointed at by the nixvim flake)\n- `module`: The nix module definition used to extend nixvim.\n  This is useful to pass additional module machinery like `options` or `imports`.\n- `extraSpecialArgs`: Extra arguments to pass to the modules when using functions.\n  Can be `self` in a flake, for example.\n\nFor more detail, see the [Standalone Usage](https://nix-community.github.io/nixvim/platforms/standalone.html) section of our documentation.\n\n### With a `devShell`\n\nYou can also use nixvim to define an instance which will only be available inside a Nix `devShell`:\n\n\u003cdetails\u003e\n  \u003csummary\u003edevShell configuration\u003c/summary\u003e\n\n```nix\nlet\n  nvim = nixvim.legacyPackages.x86_64-linux.makeNixvim {\n    plugins.lsp.enable = true;\n  };\nin pkgs.mkShell {\n  buildInputs = [nvim];\n};\n```\n\n\u003c/details\u003e\n\n# Documentation\nDocumentation is available on this project's GitHub Pages page:\n[https://nix-community.github.io/nixvim](https://nix-community.github.io/nixvim)\n\nThe stable documentation is also available at [https://nix-community.github.io/nixvim/24.11](https://nix-community.github.io/nixvim/24.11).\n\nIf the option `enableMan` is set to `true` (by default it is), man pages will also\nbe installed containing the same information, they can be viewed with `man nixvim`.\n\n## Plugins\nAfter you have installed NixVim, you will no doubt want to enable some plugins.\nPlugins are based on a modules system, similarly to NixOS and Home Manager.\n\nSo, to enable some supported plugin, all you have to do is enable its module:\n\n```nix\n{\n  programs.nixvim = {\n    plugins.lightline.enable = true;\n  };\n}\n```\n\nOf course, if that was everything, there wouldn't be much point to NixVim, you'd\njust use a regular plugin manager. All options for supported plugins are exposed\nas options of that module. For now, there is no documentation yet, but there are\ndetailed explanations in the source code. Detailed documentation for every\nmodule is planned.\n\nNot all plugins will have modules, so you might still want to fetch some. This\nis not a problem, just use the `extraPlugins` option:\n\n```nix\n{\n  programs.nixvim = {\n    extraPlugins = with pkgs.vimPlugins; [\n      vim-nix\n    ];\n  };\n}\n```\n\nHowever, if you find yourself doing this a lot, please consider\ncontributing or requesting a module!\n\n### Colorschemes\nColorschemes are provided within a different scope:\n\n```nix\n{\n  programs.nixvim = {\n    # Enable gruvbox\n    colorschemes.gruvbox.enable = true;\n  };\n}\n```\n\nJust like with normal plugins, extra colorscheme options are provided as part\nof its module.\n\nIf your colorscheme isn't provided as a module, install it using\n`extraPlugins` and set it using the `colorscheme` option:\n\n```nix\n{\n  programs.nixvim = {\n    extraPlugins = [ pkgs.vimPlugins.gruvbox ];\n    colorscheme = \"gruvbox\";\n  };\n}\n```\n\nAll NixVim supported plugins will, by default, use the main colorscheme you\nset, though this can be overridden on a per-plugin basis.\n\n## Options\nNeoVim has a lot of configuration options. You can find a list of them by doing\n`:h option-list` from within NeoVim.\n\nAll of these are configurable from within NixVim. All you have to do is set the\n`opts` attribute:\n\n```nix\n{\n  programs.nixvim = {\n    opts = {\n      number = true;         # Show line numbers\n      relativenumber = true; # Show relative line numbers\n\n      shiftwidth = 2;        # Tab width should be 2\n    };\n  };\n}\n```\n\nPlease note that to, for example, disable numbers you would not set\n`opts.nonumber` to true, you'd set `opts.number` to false.\n\n## Key mappings\nIt is fully possible to define key mappings from within NixVim. This is done\nusing the `keymaps` attribute:\n\n```nix\n{\n  programs.nixvim = {\n    keymaps = [\n      {\n        key = \";\";\n        action = \":\";\n      }\n      {\n        mode = \"n\";\n        key = \"\u003cleader\u003em\";\n        options.silent = true;\n        action = \"\u003ccmd\u003e!make\u003cCR\u003e\";\n      }\n    ];\n  };\n}\n```\n\nThis is equivalent to this vimscript:\n\n```vim\nnoremap ; :\nnnoremap \u003cleader\u003em \u003csilent\u003e \u003ccmd\u003emake\u003cCR\u003e\n```\n\nThis table describes all modes for the `keymaps` option.\nYou can provide several modes to a single mapping by using a list of strings.\n\n\u003c!-- Based on `:h map-table` https://neovim.io/doc/user/map.html#map-table --\u003e\n\n| Mode   | Norm | Ins | Cmd | Vis | Sel | Opr | Term | Lang | Description |\n|--------|------|-----|-----|-----|-----|-----|------|------|-------------|\n| `\"\"`   | yes  |  -  |  -  | yes | yes | yes |  -   |  -   | Equivalent to `:map` |\n| `\"n\"`  | yes  |  -  |  -  |  -  |  -  |  -  |  -   |  -   | Normal mode |\n| `\"!\"`  |  -   | yes | yes |  -  |  -  |  -  |  -   |  -   | Insert and command-line mode |\n| `\"i\"`  |  -   | yes |  -  |  -  |  -  |  -  |  -   |  -   | Insert mode |\n| `\"c\"`  |  -   |  -  | yes |  -  |  -  |  -  |  -   |  -   | Command-line mode |\n| `\"v\"`  |  -   |  -  |  -  | yes | yes |  -  |  -   |  -   | Visual and Select mode |\n| `\"x\"`  |  -   |  -  |  -  | yes |  -  |  -  |  -   |  -   | Visual mode only, without select |\n| `\"s\"`  |  -   |  -  |  -  |  -  | yes |  -  |  -   |  -   | Select mode |\n| `\"o\"`  |  -   |  -  |  -  |  -  |  -  | yes |  -   |  -   | Operator-pending mode |\n| `\"t\"`  |  -   |  -  |  -  |  -  |  -  |  -  | yes  |  -   | Terminal mode |\n| `\"l\"`  |  -   | yes | yes |  -  |  -  |  -  |  -   | yes  | Insert, command-line and lang-arg mode |\n| `\"!a\"` |  -   | abr | abr |  -  |  -  |  -  |  -   |  -   | [Abbreviation] in insert and command-line mode |\n| `\"ia\"` |  -   | abr |  -  |  -  |  -  |  -  |  -   |  -   | [Abbreviation] in insert mode |\n| `\"ca\"` |  -   |  -  | abr |  -  |  -  |  -  |  -   |  -   | [Abbreviation] in command-line mode |\n\nEach keymap can specify the following settings in the `options` attrs.\n\n[Abbreviation]: https://neovim.io/doc/user/usr_24.html#_abbreviations\n\n| NixVim  | Default | VimScript                                         |\n|---------|---------|---------------------------------------------------|\n| silent  | false   | `\u003csilent\u003e`                                        |\n| nowait  | false   | `\u003csilent\u003e`                                        |\n| script  | false   | `\u003cscript\u003e`                                        |\n| expr    | false   | `\u003cexpr\u003e`                                          |\n| unique  | false   | `\u003cunique\u003e`                                        |\n| noremap | true    | Use the 'noremap' variant of the mapping          |\n| remap   | false   | Make the mapping recursive (inverses `noremap`)   |\n| desc    | \"\"      | A description of this keymap                      |\n\n## Globals\nSometimes you might want to define a global variable, for example to set the\nleader key. This is easy with the `globals` attribute:\n\n```nix\n{\n  programs.nixvim = {\n    globals.mapleader = \",\"; # Sets the leader key to comma\n  };\n}\n```\n\n## Additional config\nSometimes NixVim won't be able to provide for all your customization needs.\nIn these cases, the `extraConfigVim` and `extraConfigLua` options are\nprovided:\n\n```nix\n{\n  programs.nixvim = {\n    extraConfigLua = ''\n      -- Print a little welcome message when nvim is opened!\n      print(\"Hello world!\")\n    '';\n  };\n}\n```\n\nIf you feel like what you are doing manually should be supported in NixVim,\nplease open an issue.\n\n# Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnix-community%2Fnixvim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnix-community%2Fnixvim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnix-community%2Fnixvim/lists"}