Catppuccin Neovim Setup: Install and Configure the Theme

Catppuccin for Neovim can be a one-line colorscheme or the visual layer that ties together Treesitter, LSP diagnostics, completion menus, file explorers, statuslines, and pickers. The official port supports all four Catppuccin flavors and knows how to style a long list of popular plugins. A good setup starts small: load the theme early, choose a flavor, and enable only the integrations your configuration actually uses.

This guide shows a clean Catppuccin Neovim setup with lazy.nvim, the built-in vim.pack available in newer Neovim releases, and a manual fallback. It also explains the options worth changing and the common reasons a theme looks different from its screenshots.

Before you install Catppuccin

The maintained Catppuccin port supports Neovim 0.8 or newer. Check your version before debugging a plugin-manager error:

nvim --version

Your main configuration normally lives at ~/.config/nvim/init.lua on Linux and macOS. On Windows it is commonly under %LOCALAPPDATA%\nvim\init.lua. If you use a structured configuration, keep the Catppuccin plugin specification with the rest of your plugin files rather than copying every example into init.lua.

The official repository is catppuccin/nvim. Use that exact source. Similar names may be old ports, Vim-only packages, or personal forks.

Install Catppuccin with lazy.nvim

For lazy.nvim, give Catppuccin a high priority so it loads before plugins that calculate their highlights from the active colorscheme:

{
  "catppuccin/nvim",
  name = "catppuccin",
  priority = 1000,
  config = function()
    require("catppuccin").setup({
      flavour = "mocha",
    })

    vim.cmd.colorscheme("catppuccin-nvim")
  end,
}

If this table is inside the list passed to require("lazy").setup(), restart Neovim and run :Lazy sync. The explicit name = "catppuccin" gives the plugin the module name expected by require("catppuccin"). The priority matters only when the plugin is not lazy-loaded, so do not add an event such as VeryLazy to the colorscheme specification.

You can omit the setup() call when the defaults are enough:

{
  "catppuccin/nvim",
  name = "catppuccin",
  priority = 1000,
  config = function()
    vim.cmd.colorscheme("catppuccin-nvim")
  end,
}

Install with Neovim's built-in vim.pack

Neovim 0.12 introduces vim.pack as a built-in package workflow. If your version provides it, add Catppuccin and then activate the theme:

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

require("catppuccin").setup({
  flavour = "mocha",
})

vim.cmd.colorscheme("catppuccin-nvim")

Do not copy this block into Neovim 0.10 or 0.11 and expect vim.pack to exist. Use your current plugin manager instead. Catppuccin also documents installation with packer-style managers and rocks.nvim, but a working manager does not need to be replaced just for a colorscheme.

Manual installation without a plugin manager

For a simple manual install, clone the repository into Neovim's package path:

git clone https://github.com/catppuccin/nvim \
  ~/.local/share/nvim/site/pack/catppuccin/start/catppuccin

Then add this to init.lua:

require("catppuccin").setup({
  flavour = "mocha",
})

vim.cmd.colorscheme("catppuccin-nvim")

Manual cloning works, but updates become your responsibility. Pull changes from that directory when you want a new release. A plugin manager is usually the better long-term choice because it records the source, handles updates, and makes a configuration easier to reproduce.

Choose Latte, Frappé, Macchiato, or Mocha

The flavour option accepts latte, frappe, macchiato, mocha, or auto. The Lua spelling is deliberately flavour. Using flavor will not configure the theme.

Mocha is the recognizable default for a dark Neovim setup. Macchiato is often easier on laptop panels because comments, line numbers, and inactive elements have more room to separate from the background. Use Latte because you want light mode, not merely to make the editor unusual.

To follow Neovim's background setting automatically, use:

require("catppuccin").setup({
  flavour = "auto",
  background = {
    light = "latte",
    dark = "mocha",
  },
})

Then :set background=light selects Latte and :set background=dark selects Mocha. This is useful when a terminal or operating-system hook already changes Neovim's background preference.

A practical daily configuration

The following setup keeps the palette recognizable, colors the built-in terminal, leaves window backgrounds opaque, and enables automatic plugin-integration detection:

require("catppuccin").setup({
  flavour = "mocha",
  transparent_background = false,
  term_colors = true,
  float = {
    transparent = false,
    solid = false,
  },
  dim_inactive = {
    enabled = false,
  },
  styles = {
    comments = { "italic" },
    conditionals = { "italic" },
    loops = {},
    functions = {},
    keywords = {},
    strings = {},
    variables = {},
    numbers = {},
    booleans = {},
    properties = {},
    types = {},
    operators = {},
  },
  auto_integrations = true,
})

vim.cmd.colorscheme("catppuccin-nvim")

Call setup() before vim.cmd.colorscheme(). Loading the colorscheme first compiles highlights from the defaults; changing options afterward can appear to do nothing until the theme is reloaded.

Transparency: theme setting versus terminal setting

Set transparent_background = true when you want Neovim's main windows to stop painting their background:

require("catppuccin").setup({
  transparent_background = true,
  float = {
    transparent = true,
  },
})

This does not create blur or transparency by itself. Your terminal emulator and desktop compositor still control what appears behind Neovim. If the editor becomes transparent but floating windows remain solid, configure float.transparent separately. If text becomes difficult to read over wallpaper, keep floating menus opaque or return the main background to Base.

Style comments, keywords, and diagnostics

The styles table controls broad highlight categories. An italic style only works if the terminal and font provide a real italic face. To remove all italic styling, the shortest option is:

require("catppuccin").setup({
  no_italic = true,
})

Catppuccin also exposes lsp_styles for diagnostic virtual text, underlines, and inlay hints. Keep errors distinguishable by more than color when possible: an underline plus a diagnostic sign survives displays where subtle red and peach tones look similar.

Plugin integrations

Catppuccin contains highlight modules for many common Neovim plugins. Current versions enable auto_integrations by default for supported package workflows, detecting installed plugins and applying their integrations. You can still declare important integrations explicitly:

require("catppuccin").setup({
  auto_integrations = true,
  integrations = {
    blink_cmp = true,
    cmp = true,
    gitsigns = true,
    nvimtree = true,
    telescope = true,
    treesitter = true,
    native_lsp = {
      enabled = true,
    },
  },
})

Only enable names supported by the version you installed. Plugin ecosystems change faster than the core palette, so the official integrations list is the source of truth. If an integration has a nested configuration, copy its current shape rather than guessing a Boolean.

Load-order rules can still matter. For example, a bufferline or statusline may calculate its own highlights during setup. If it starts before Catppuccin, it may retain fallback colors. Give Catppuccin high priority and follow the integration's documented order.

Override one highlight without forking the theme

Use custom_highlights when the palette is right but one group needs more contrast:

require("catppuccin").setup({
  custom_highlights = function(colors)
    return {
      Comment = { fg = colors.overlay1, style = { "italic" } },
      LineNr = { fg = colors.surface2 },
      CursorLineNr = { fg = colors.mauve, style = { "bold" } },
    }
  end,
})

The callback receives the active flavor's named colors, so the override continues to make sense if you move from Mocha to Macchiato. Raw hex overrides are useful for deliberate custom palettes; named colors are safer for normal tuning.

When a change does not affect the token you expected, inspect it with :Inspect in recent Neovim versions. Treesitter captures, semantic tokens, and plugin-specific highlight groups may sit on top of the older Comment or Function group.

Common Catppuccin Neovim problems

E185: Cannot find color scheme

The plugin is not on Neovim's runtime path when the colorscheme command runs. In lazy.nvim, keep the colorscheme eager, set priority = 1000, and avoid late-loading events. Confirm the repository is catppuccin/nvim and the configured plugin name is catppuccin.

Module 'catppuccin' not found

The package did not install, was given a conflicting name, or loads after the configuration file that calls require(). Run your plugin manager's sync or install command, inspect its error log, and restart Neovim before changing theme code.

The flavor setting is ignored

Check the spelling flavour, then make sure setup() appears before the colorscheme command. Also search the rest of your configuration for a second colorscheme call that runs later and replaces Catppuccin.

Treesitter or LSP colors look incomplete

Confirm Treesitter parsers and language servers are working independently of the theme. Catppuccin styles highlight groups that those tools expose; it cannot generate missing captures or semantic tokens. Run :checkhealth, update the relevant plugin, and use :Inspect on an affected token.

Transparency shows ugly blocks

A plugin window is probably assigning its own background highlight. Enable the matching Catppuccin integration, inspect that window's groups, or override only those groups. Making every background NONE globally often removes useful boundaries from completion menus and floating documentation.

Where to stop customizing

A sensible first setup is Mocha or Macchiato, an opaque Base background, automatic integrations, italic comments, and terminal colors enabled. Use it for a day. Then change the one thing you notice during work—not the ten things that looked interesting in a dotfiles screenshot.

If you also use Microsoft's editor, the published Catppuccin VS Code setup guide applies the same flavors to that workbench. If you are still choosing between pastel and neon rather than configuring Neovim, read Tokyo Night vs Catppuccin.

The finished configuration should be boring in the best way: Catppuccin loads before the plugins that depend on it, your chosen flavor remains readable in the room where you work, and the theme disappears behind the code.

Plugin names, supported versions, option shapes, and installation examples were checked against the official Catppuccin for Neovim repository.