# kanagawa.nvim: a Hokusai-inspired Neovim colorscheme with three themes

> kanagawa.nvim is an MIT-licensed dark colorscheme for Neovim built around a two-layer color model. It ships three variants, supports TreeSitter and many plugins, and can compile itself to Lua bytecode. Here is how the install, config and customization actually work, and where the design asks you to do the work.

**rebelot/kanagawa.nvim** — NeoVim dark colorscheme inspired by the colors of the famous painting by Katsushika Hokusai.

- Repository: https://github.com/rebelot/kanagawa.nvim
- Stars: 6,412 · Forks: 236
- Language: Lua
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/rebelot-kanagawa-nvim

## What kanagawa.nvim solves, and for whom

Most Neovim colorschemes give you a fixed list of highlight groups. If you want a different background in floating windows, or a different color for function parameters, you either fork the theme or write a pile of highlight overrides. kanagawa.nvim splits the problem in two: a palette of named RGB hex colors, and a theme that maps those palette entries onto semantic names. The README describes the split directly: PaletteColors are "defined directly as RGB Hex strings, and have arbitrary names that recall their actual color", while ThemeColors are "named and grouped semantically on the basis of their actual function". A palette color can feed several theme colors, so changing one hex value can move many highlights at once.

The audience is Neovim users who care about that distinction. If you only want to type colorscheme kanagawa and move on, the README says there is no need to call setup at all. The layering only matters once you start editing colors, and then it saves you from chasing individual highlight groups across the theme.

## Three themes and the background option

Kanagawa ships three variants. The README calls wave "the default heart-warming theme", dragon is "for those late-night sessions", and lotus is "for when you're out in the open". You can pick one in three ways: set config.theme, let the value of vim.o.background choose through config.background, or load the variant directly.

The background mapping is the interesting part. The default config maps dark to wave and light to lotus, and the README suggests trying dragon for dark. Any change to vim.o.background selects the mapped theme, so a single option flips the whole colorscheme. That is convenient, but it also means the mapping is a config decision you can get wrong: if you set background.dark to dragon, every dark-mode switch lands on dragon, not wave.

Direct loading bypasses setup entirely:

```lua
vim.cmd("colorscheme kanagawa-wave")
vim.cmd("colorscheme kanagawa-dragon")
vim.cmd("colorscheme kanagawa-lotus")
```

There is also a Lua entry point, require("kanagawa").load("wave"), which the README lists alongside the colorscheme commands.

## Installing kanagawa.nvim and loading it for the first time

The README gives one installation line, for a plugin manager that uses the use syntax:

```lua
use "rebelot/kanagawa.nvim"
```

The requirements are short: neovim latest, truecolor terminal support, and undercurl terminal support as an optional extra. If your terminal does not do truecolor, the palette will not render as intended, so check that before judging the theme.

Loading it needs one command. The README shows both forms:

```vim
colorscheme kanagawa
```

```lua
vim.cmd("colorscheme kanagawa")
```

That is the whole first use. No setup call is required for defaults, and the README states this explicitly. What you should see after running it is the wave theme, since wave is the default, with TreeSitter highlighting applied to your buffers.

If you do want to configure it, setup must run before the colorscheme is loaded:

```lua
require('kanagawa').setup({
    compile = false,
    undercurl = true,
    commentStyle = { italic = true },
    functionStyle = {},
    keywordStyle = { italic = true},
    statementStyle = { bold = true },
    typeStyle = {},
    transparent = false,
    dimInactive = false,
    terminalColors = true,
    theme = "wave",
})
vim.cmd("colorscheme kanagawa")
```

Those are the defaults as printed in the README, so passing them changes nothing. The ordering matters more than the values: the README's note 2 says kanagawa adjusts to some options and that laststatus and cmdheight must be set before setup is called. Get that order wrong and the statusline and command line colors will not match the rest of the theme.

## Editing the palette and theme layers

Customization goes through config.colors, which has two keys. palette holds hex values keyed by names like sumiInk0 and fujiWhite. theme holds overrides scoped to a variant (wave, dragon, lotus) or to all of them. The README points to lua/kanagawa/colors.lua for the full list of palette names and lua/kanagawa/themes.lua for how each theme uses them. Those two files are where you look before inventing a name, because a typo in a palette key is not something the theme will tell you about.

A theme override can target a nested path such as ui.float.bg or syn.parameter, and the all key applies the same override everywhere:

```lua
colors = {
    theme = {
        wave = {
            ui = {
                float = {
                    bg = "none",
                },
            },
        },
        all = {
            ui = {
                bg_gutter = "none"
            }
        }
    }
}
```

For anything the theme layer does not name, config.overrides is a function that receives the resolved colors and returns highlight groups. The README says the supported keywords match the {val} parameter of :h nvim_set_hl. The distinction it draws is worth keeping: a static color like colors.palette.carpYellow is fixed, while colors.theme.syn.type updates when you switch theme. Mixing the two in one overrides function is how you end up with a highlight that ignores your theme change.

```lua
overrides = function(colors)
    return {
        String = { fg = colors.palette.carpYellow, italic = true },
        SomePluginHl = { fg = colors.theme.syn.type, bold = true },
    }
end
```

## The compile step and its maintenance cost

Kanagawa can compile itself to Lua bytecode, which the README lists as a feature for "super fast startup times". The cost is a manual step. Note 1 says that if you enable compilation, you must run :KanagawaCompile every time you change your config. The README spells out the sequence: modify the config, restart nvim, then run the command.

```vim
:KanagawaCompile
```

This is the sharpest trade-off in the project. Compilation is off by default (compile = false), and the reason to leave it off is that forgetting the command means your edits silently do not appear. The failure mode is not an error message, it is a theme that looks like the old one. If you tune colors often, the manual recompile is friction you have to accept or avoid by keeping compile disabled.

The project has no releases listed, so there is no versioned upgrade path to reason about. You track the master branch and take changes as they come. The last push was on 2026-05-10, so the repository is not archived and has been touched within the last six months. The README does not document a rollback procedure if a change to the theme files breaks your overrides, which is the practical risk of following a branch: your config references palette names and theme paths that the project controls.

## Where kanagawa.nvim is the wrong choice

The theme is dark-first. Wave and dragon are both dark variants, and lotus is the light one. If you want a light colorscheme as your default, you are choosing between one variant and whatever the background mapping does when vim.o.background flips, which is a narrower offering than a project that treats light and dark as equal citizens.

The README is also honest about the environment it assumes. Truecolor terminal support is a requirement, not a suggestion, and undercurl support is listed as optional. On a terminal without truecolor the palette degrades, and the careful hex values in colors.lua stop meaning what they meant. That is a constraint of the medium rather than a defect, but it rules the theme out for constrained terminals.

Finally, the customization model assumes you are comfortable reading Lua source. The README sends you to lua/kanagawa/colors.lua and lua/kanagawa/themes.lua to find names, and the overrides function hands you a colors table to inspect. If you want a GUI color picker or a documented list of every highlight group in the README itself, this is not that project. The documentation covers the mechanism and the common customizations, and leaves the full surface to the source files.

## How it compares with a single-file colorscheme

The obvious alternative is a colorscheme that defines its highlight groups in one file with hardcoded hex values and no palette indirection. That approach is simpler to read and has no compile step, no ordering rule about laststatus and cmdheight, and no separate theme and palette namespaces to learn. If you never intend to change a color, it is the better fit, because kanagawa's structure is overhead you would not use.

The difference shows up when you do want changes. With a single-file theme, recoloring every function signature means finding each highlight group that draws one. With kanagawa.nvim, you change the palette entry or the theme key that those groups share, and the README's example of setting sumiInk0 to #000000 is exactly that move: one value, all usages. You give up directness and gain a level of indirection that pays off only if you edit colors more than once.

The second alternative is writing a small overrides block on top of whichever theme you already use. That keeps your current colors and patches the parts you dislike. It is less work than adopting a new palette, but it inherits the base theme's structure, so a change to that theme can move the ground under your overrides. Kanagawa's theme files are the thing you would be editing anyway, in a project that expects it.

## Conclusion

Adopt kanagawa.nvim if you want a Neovim colorscheme whose palette and semantic theme layers can be edited separately, and you are willing to set laststatus and cmdheight before calling setup. Skip it if you need a light-only theme or you refuse to run :KanagawaCompile after every config change while compile is enabled. Verify first that your terminal reports truecolor, then load each of kanagawa-wave, kanagawa-dragon and kanagawa-lotus and check your own filetypes and plugin highlights, since the README documents the palette and theme files but not per-plugin coverage.

## FAQ

### How do I install kanagawa.nvim?

The README gives a single line for plugin managers that use the use syntax: use "rebelot/kanagawa.nvim". After that, load it with colorscheme kanagawa. No setup call is needed if the defaults are fine.

### What colors are in the Kanagawa theme color palette?

Palette colors are defined as RGB hex strings with names that recall the color, such as sumiInk0 and fujiWhite. The README points to lua/kanagawa/colors.lua for the full list of palette names and lua/kanagawa/themes.lua for how each theme uses them.

### Which themes does kanagawa.nvim ship?

Three: wave, the default, dragon for late-night sessions, and lotus for light use. You can select one through config.theme, through the background mapping, or by loading kanagawa-wave, kanagawa-dragon or kanagawa-lotus directly.

### Why do my kanagawa.nvim config changes not appear?

If compile is enabled, the README says you must run :KanagawaCompile after every config change, following a restart of nvim. Compilation is off by default, so leaving compile set to false avoids the manual step.

### What does kanagawa.nvim require before setup runs?

The README states that the options laststatus and cmdheight must be set before calling setup, because kanagawa adjusts to their values. It also requires neovim latest and truecolor terminal support, with undercurl support optional.

## Sources

- [Issues](https://github.com/rebelot/kanagawa.nvim/issues)
- [License: MIT](https://github.com/rebelot/kanagawa.nvim/blob/master/LICENSE)
- [README](https://github.com/rebelot/kanagawa.nvim/blob/master/README.md)
- [rebelot/kanagawa.nvim on GitHub](https://github.com/rebelot/kanagawa.nvim)

---

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