# catppuccin/nvim: a pastel Neovim colourscheme with compiled config and plugin integrations

> The original Catppuccin port ships four flavours, a lazy-loadable compiled config and an integration table that reaches into LSP, treesitter and dozens of plugins. This is a review of what it actually does, how to install it, and where the design costs you.

**catppuccin/nvim** — 🍨 Soothing pastel theme for Neovim

- Repository: https://github.com/catppuccin/nvim
- Stars: 7,640 · Forks: 338
- Language: Lua
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/catppuccin-nvim

## What catppuccin/nvim actually solves

A colourscheme is not a list of hex codes. In Neovim it is a set of highlight groups, and the groups are produced by the core editor, by LSP, by treesitter and by every plugin that draws its own UI. A hand-written theme covers the core groups and leaves the rest to look like a different editor. catppuccin/nvim exists to close that gap: the README lists "Integrations with lsp, treesitter and a bunch of plugins" as a feature, and the repository carries an `integrations` table in the setup options where plugins such as cmp, gitsigns and nvimtree are switched on by name.

The audience is therefore narrower than "anyone who wants pastel colours". You are the intended user if you run Neovim 0.8 or newer, you have several plugins that draw UI, and you would rather flip `gitsigns = true` than hunt down the highlight group names yourself. If your configuration is the core editor plus a file finder, the integration surface is mostly dead weight.

## Four flavours, auto background and the compile step

The theme ships four flavours: Latte, Frappé, Macchiato and Mocha. Latte is the light one; the other three are dark. The `flavour` option defaults to `"auto"`, and the `background` table maps `light` to `latte` and `dark` to `mocha`, so the scheme follows whatever `:h background` reports unless you pin a flavour explicitly.

Options are grouped in a single `setup` call. `transparent_background` disables setting the background colour, which is the switch behind the "catppuccin nvim transparent" searches. `dim_inactive` dims inactive windows and takes a `shade` and a `percentage`. `styles` and `lsp_styles` control italics, bold and underline per highlight family rather than globally, so you can italicise comments and leave functions upright. `color_overrides` and `custom_highlights` handle palette and group tweaks.

The compile step is the part worth understanding before you adopt it. The README describes a "Compiled configuration for fast startup time", and the repository root contains `nvim.tera`, a template file, plus a `scripts/` directory. The idea is that you run the compile command once, the theme writes a Lua file with all highlight groups resolved, and Neovim sources that instead of computing the groups at startup. The trade-off is direct: the compiled artifact is a cache. Change an option and the cache is stale until you compile again. The README does not document an automatic invalidation path, so treat compilation as a step you own.

## Installing catppuccin/nvim with lazy.nvim, vim.pack or rocks.nvim

The README gives four installation paths. For Neovim 0.12's built-in `vim.pack`, the spec is a single `add` call. Note that the plugin is registered under the name `catppuccin`, not `nvim`, because the colourscheme command depends on that name.

```lua
vim.pack.add { { src = "https://github.com/catppuccin/nvim", name = "catppuccin" } }
```

With lazy.nvim the README shows a `priority = 1000` entry, which pushes the plugin ahead of everything else in the load order. That matters: a colourscheme loaded after the plugins it styles leaves those plugins unstyled.

```lua
{ "catppuccin/nvim", name = "catppuccin", priority = 1000 }
```

packer.nvim uses the `as` key for the same reason.

```lua
use { "catppuccin/nvim", as = "catppuccin" }
```

rocks.nvim installs it as a rock from inside Neovim.

```vim
:Rocks install catppuccin.nvim
```

Once installed, applying it is one command. The README lists the four colourscheme names in a comment: `catppuccin-latte`, `catppuccin-frappe`, `catppuccin-macchiato` and `catppuccin-mocha`.

```vim
colorscheme catppuccin-nvim " catppuccin-latte, catppuccin-frappe, catppuccin-macchiato, catppuccin-mocha
```

The Lua equivalent is `vim.cmd.colorscheme "catppuccin-nvim"`. If you want the default options, the README states there is no need to call `setup` at all. The moment you want a different flavour or a transparent background, you do.

## Configuring flavour, transparency and per-group styles

A first real configuration is short. This pins Mocha, turns on a transparent background and asks for italic comments, which is the shape of most user configs the README's option list supports.

```lua
require("catppuccin").setup({
    flavour = "mocha",
    transparent_background = true,
    styles = {
        comments = { "italic" },
        conditionals = { "italic" },
    },
})
vim.cmd.colorscheme "catppuccin-nvim"
```

Two keys are easy to miss. `auto_integrations` defaults to `true`, so the theme tries to detect supported plugins on its own; the explicit `integrations` table is how you override that per plugin. `term_colors` defaults to `false` and, when enabled, sets terminal colours such as `g:terminal_color_0`. If your `:terminal` output looks wrong after switching, that key is the first place to look.

For LSP, the `lsp_styles` table is separate from `styles`. It carries `virtual_text`, `underlines` and `inlay_hints` sub-tables, so diagnostic text and diagnostic underlines can be styled independently. `inlay_hints` takes a `background` boolean. The README does not document what happens when a plugin in the `integrations` table is not installed; the safe reading is that detection is best-effort and an explicit `true` for a missing plugin is your problem, not the theme's.

## Where catppuccin/nvim is the wrong choice

Vim. The README is blunt about it: support for Vim lives on the `vim` branch, that branch "won't receive further updates unless necessary", and Vim support has been dropped. The note points Vim users at catppuccin/vim instead. It also records that starting from Vim v9.2.0219 and Neovim 0.12, `catppuccin` ships with the editors, and that the bundled copy is not maintained by the Catppuccin organization and follows Vim colorscheme rules rather than the official Catppuccin style guide. If you installed Neovim 0.12 and wondered why the theme looks slightly different from the screenshots, that is why.

The second limitation is the compile cache. It is an optimisation you have to maintain. Every edit to `flavour`, `styles`, `color_overrides` or `custom_highlights` is a candidate for recompilation, and the README does not describe a rollback path if a compiled file goes wrong. Deleting the generated artifact and recompiling is the obvious recovery, but you are inferring that, not reading it.

The third is scope. This is a colourscheme, not a configuration framework. It will not pick your plugins, and the integration list is finite. If your setup leans on a plugin the README's integration table does not mention, you are writing `custom_highlights` entries by hand, which is exactly the work the theme was supposed to remove.

## How it compares to a plain Vim colourscheme

The honest alternative is a single-file `.vim` colourscheme: a list of `highlight` statements, no setup function, no compile step, no integration table. It loads instantly because there is nothing to compute, and it never goes stale because there is no cache. What it does not do is know that you use treesitter, or that your git gutter plugin has its own group names. You discover the gaps visually, one unstyled element at a time, and patch them in your own config.

catppuccin/nvim takes the opposite position: it accepts a configuration surface and a build step in exchange for covering those groups for you. That is a real trade, not a free upgrade. The plugin is also part of a wider family. The README states that this port "was the first one and the one that originated the project itself", and links to Catppuccin for many other applications, which is relevant if you want the same palette in your terminal, status bar and window manager. A standalone `.vim` file gives you one editor and nothing else.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-09. Recent releases are v2.0.0 (2026-04-02), v1.11.0 (2025-07-31) and v1.10.0 (2025-05-04), so the 2.0 line is recent and the gap between 1.11.0 and 2.0.0 was roughly eight months. A major version bump in a colourscheme usually means option or highlight-group changes, and the repository keeps a CHANGELOG.md at the root, which is where to read what moved before you upgrade.

The licence is MIT. In practice that means you can copy the theme, fork it, or vendor it into a dotfiles repository, provided you keep the licence text. It does not grant you the Catppuccin name or logo, and the README links to a style guide for ports, which suggests the organization cares about how derivatives present themselves. That is a project norm, not a licence term.

The upgrade cost is low but not zero. Because the theme is a plugin, upgrading means updating it through whatever manager installed it, then recompiling if you use the compiled config, then checking the CHANGELOG for renamed keys. The `renovate.json` file at the repository root indicates the maintainers automate dependency updates on their side, which says nothing about your side.

## Conclusion

Adopt catppuccin/nvim if you run Neovim 0.8 or newer, want one colourscheme that already knows about your LSP, treesitter and plugin highlight groups, and are willing to run the compile step after changing options. Do not adopt it if you are on Vim (the vim branch is dropped), if you want a theme with no configuration surface at all, or if you expect the shipped-with-the-editor copy to behave like this plugin. Verify first that your Neovim version meets the 0.8 floor, that lazy.nvim loads it with priority = 1000, and that the integrations you rely on are listed in the README's integration table rather than assumed.

## FAQ

### How do I install catppuccin/nvim?

The README gives four paths: `vim.pack.add` on Neovim 0.12, a lazy.nvim spec with `priority = 1000`, a packer.nvim `use` line with `as = "catppuccin"`, or `:Rocks install catppuccin.nvim` under rocks.nvim. In every case the plugin must be named `catppuccin`, because the colourscheme command depends on it.

### What is catppuccin/nvim?

It is the Neovim port of the Catppuccin colourscheme, written in Lua and licensed MIT. The README states this port was the first one and the one that originated the project, and it ships four flavours: Latte, Frappé, Macchiato and Mocha.

### What licence does catppuccin/nvim use?

MIT. The repository carries a LICENSE.md at the root and the licence field on the project is MIT.

### Why is catppuccin so popular?

The README does not discuss popularity, and nothing in the repository explains it. What it does record is that this Neovim port was the first Catppuccin port and the one that originated the project, and that the palette is available for many other applications.

### What is the best Neovim theme?

There is no ranking here to draw on, so no answer to that. What can be said is what catppuccin/nvim offers: four flavours, a compiled config for startup time, and integrations with lsp, treesitter and a list of plugins configured through the `integrations` table.

## Sources

- [catppuccin/nvim on GitHub](https://github.com/catppuccin/nvim)
- [Issues](https://github.com/catppuccin/nvim/issues)
- [License: MIT](https://github.com/catppuccin/nvim/blob/main/LICENSE)
- [README](https://github.com/catppuccin/nvim/blob/main/README.md)
- [Releases](https://github.com/catppuccin/nvim/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/catppuccin-nvim