# morhetz/gruvbox: the original Vim color scheme and what its repository actually contains

> gruvbox is a light and dark Vim color scheme built around a pastel retro palette. This review covers what the repository ships, how the 256-color terminal script works, and where the project's own documentation stops.

**morhetz/gruvbox** — Retro groove color scheme for Vim

- Repository: https://github.com/morhetz/gruvbox
- Stars: 15,772 · Forks: 1,124
- Language: Vim Script
- License: not declared
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/morhetz-gruvbox

## What gruvbox actually is, and who it is for

gruvbox is a Vim color scheme. The README describes it as a bright theme with pastel 'retro groove' colors and light/dark mode switching in the way of solarized, and names badwolf, jellybeans and solarized as its influences. The stated design goal is narrower than most theme READMEs admit: keep colors easily distinguishable, contrast enough, and still pleasant for the eyes. That is a legibility claim, not an aesthetic one, and it explains why the palette is built around a small set of warm neutrals rather than a wide hue range.

The audience is people who live inside Vim and want one repository that supplies both a dark and a light variant, plus a contrast knob, without pulling in a theme manager. The README lists extended filetype highlighting for a long set of languages (Html, Xml, Vim, Clojure, C, Python, JavaScript, TypeScript, PureScript, CoffeeScript, Ruby, Objective-C, Go, Lua, MoonScript, Java, Markdown, Haskell, Elixir) and names supported plugins including Airline, Lightline, GitGutter, Signify, Syntastic, Ale, CtrlP, Startify, NERDTree and Dirvish. If your editor is not Vim, this repository is not the artifact you want: the ports live elsewhere, in the gruvbox-contrib repository that the README links under Contributions.

## The repository layout: colors, autoload, and two shell scripts

The top level holds .github/, CHANGELOG.md, README.md, autoload/, colors/, gruvbox_256palette.sh, gruvbox_256palette_osx.sh and package.json. That split is the whole architecture. colors/ is where Vim looks for a colorscheme file once you select gruvbox. autoload/ holds the functions the colorscheme calls at load time, which is where the contrast and italics options are resolved. Nothing here is compiled; a Vim color scheme is a script that runs when the colorscheme is selected.

The two shell scripts are the part people miss. They are not Vim plugins and they do not run inside the editor. They rewrite the terminal's 256-color palette so that the indexed colors match gruvbox, which is what the README's Attention section points at when it says to read the Terminal-specific wiki page first. The osx variant exists because the terminal palette escape sequences differ between platforms. If you run Vim in a true-color terminal, you may not need either script; if you run it in a 256-color terminal and skip the scripts, the indexed colors come from your terminal emulator rather than from gruvbox, and the result will not look like the screenshots.

package.json is worth reading before you draw conclusions about release state. It declares name gruvbox, version 2.0.0, license MIT, and a vim block with opt set to true, meaning Vim's optional package loading. The most recent release listed in the repository is v3.0.1-rc.0 from 2018-05-16, a release candidate, after v2.0.0 in 2015. The package manifest still says 2.0.0. The last push to the default branch was on 2026-09-18, so the repository is not archived and is not dormant, but the tagged releases are old and the version string in package.json does not match them. Treat the master branch, not a tag, as the thing you are installing.

## Installing gruvbox and switching to dark mode

The README does not contain install steps. It directs readers to the wiki for installation details, terminal-specific setup, troubleshooting and configuration options. What the repository does give you is the layout: colors/ holds the colorscheme and package.json marks the plugin as opt, meaning Vim's optional package loading. The two lines below are the only commands this review can trace to the repository itself, and they are the clone target and the manifest entry rather than a quoted procedure.

```bash
git clone https://github.com/morhetz/gruvbox.git
```

The repository URL above is the one in package.json and in the README's Self-Promotion section. Where you clone it to is a Vim runtime path question, and the README answers that question by pointing at the wiki rather than in the README body. The manifest's opt flag is the one concrete configuration fact available here.

```json
{
  "name": "gruvbox",
  "version": "2.0.0",
  "license": "MIT",
  "vim": {
    "opt": true
  }
}
```

That block is package.json verbatim, minus the repository and author fields. It tells you the intended loading mode is optional, and it tells you the version string the project ships. After installing, the README's Attention section is the first thing to follow: read the Terminal-specific wiki page before adjusting anything else. The README does not document a rollback procedure, so if a change breaks your setup, the wiki is the only place the project points you.

## The 256-color terminal problem

This is the failure mode that generates most of the confusion around gruvbox, and the README handles it with a single line pointing at the wiki rather than an explanation. A Vim color scheme can only set colors that the terminal is able to display. In a true-color terminal, gruvbox's hex values pass through unchanged. In a 256-color terminal, Vim falls back to the nearest indexed color, and the mapping depends on which palette the terminal emulator has loaded. Two people running the same colorscheme file can therefore see different colors.

gruvbox_256palette.sh and gruvbox_256palette_osx.sh exist to fix that by redefining the terminal's indexed palette to gruvbox values. The consequence is global: every program in that terminal, not just Vim, gets the new colors. That is a real trade-off and the README does not discuss it. If you use a terminal profile you care about, or you switch between gruvbox and another theme, you are now managing terminal state outside Vim. The scripts are also shell scripts, so they need to be sourced in the right shell and re-applied for each new terminal session unless you wire them into your shell startup file yourself. The README documents none of that.

## Where gruvbox stops and gruvbox-material starts

The most common comparison is with gruvbox-material, which appears in the search data around this project. The difference is in the palette strategy rather than the editor integration. Classic gruvbox is built on high-contrast pastel accents against warm neutral backgrounds, and the README frames the whole design around keeping colors distinguishable. gruvbox-material takes the same recognizable family of hues and lowers the contrast between foreground text and background, which is a different answer to the same eye-strain question. Neither is a superset of the other; they are two points on the contrast axis, and the repository here does not ship a material variant.

The practical difference for an adopter is configuration surface. This repository exposes contrast through the g:gruvbox_contrast_dark option documented in the wiki, so you can move along that axis without leaving the project. If your complaint is that even the low-contrast setting is too loud, the material fork is the more direct route. If your complaint is the opposite, that other themes wash out syntax distinctions, the original's stated goal is exactly the thing you want. Ports to other editors and desktop toolkits are a separate matter and live in gruvbox-contrib.

## Licence, maintenance and what an upgrade costs you

The README's License section names MIT/X11 and links to the MIT License page on Wikipedia. package.json independently declares "license": "MIT". The repository has no LICENSE file at the top level, which is a paperwork gap rather than a licensing one: two places in the project state MIT, so the terms are not ambiguous, but if your organisation requires a LICENSE file in the tree, you will be checking a box that is empty. This is not legal advice; if the distinction matters to your process, have someone who can read the actual grant confirm it.

Upgrade cost is low in the mechanical sense and awkward in the versioning sense. There is no dependency graph, no build step and no runtime to keep patched. Updating means pulling the default branch. But the tags stop at v3.0.1-rc.0 from 2018-05-16, package.json says 2.0.0, and the last push was on 2026-09-18, so commits have continued without a corresponding release. CHANGELOG.md exists in the tree, but the README does not point to it as the place to read about the interval between the last tag and the current branch. In practice you are tracking a branch, and the thing to watch after an update is whether your contrast settings still resolve, since those are read from autoload/ at load time and are the part most likely to shift.

## Conclusion

Adopt gruvbox if you run Vim in a true-color terminal and want a single repository that carries both a light and a dark palette with adjustable contrast. Skip it if you need a maintained release cadence or documented configuration, and skip it if you want a working 256-color setup without reading the wiki. Before installing, check one thing: whether your terminal already uses the gruvbox palette, because the README's first instruction is to read the Terminal-specific wiki page and that page is where the palette mismatch is explained.

## FAQ

### What is gruvbox?

gruvbox is a Vim color scheme with pastel retro colors and both a light and a dark mode. The README says it was heavily inspired by badwolf, jellybeans and solarized, and that its main focus is keeping colors easily distinguishable and pleasant for the eyes.

### How do I install gruvbox in Vim?

The README does not give install steps and points to the wiki instead. The repository layout supports cloning it into a Vim runtime path and loading it as an optional package, which package.json marks with the opt flag.

### How do I use gruvbox in Neovim?

The README does not document Neovim separately from Vim. The files that matter are the same ones: colors/ supplies the colorscheme and autoload/ resolves the contrast options, and the Terminal-specific wiki page is the README's first recommendation for setup.

### What colors are in the gruvbox theme?

The README shows a palette image for dark mode and one for light mode but does not list the color values in text. It does document a contrast option, g:gruvbox_contrast_dark, in the wiki's Configuration section, which adjusts how strongly the palette separates foreground from background.

### What is the difference between gruvbox and gruvbox-material?

This repository does not ship a material variant; gruvbox-material is a separate project. The distinction is contrast: gruvbox exposes contrast through its own configuration option, while gruvbox-material lowers the contrast between text and background as its starting point.

### Is gruvbox good for your eyes?

The README states that the main focus when developing gruvbox was to keep colors easily distinguishable, contrast enough and still pleasant for the eyes. That is a design intention stated by the project, not a measured result.

## Sources

- [Issues](https://github.com/morhetz/gruvbox/issues)
- [morhetz/gruvbox on GitHub](https://github.com/morhetz/gruvbox)
- [README](https://github.com/morhetz/gruvbox/blob/master/README.md)
- [Releases](https://github.com/morhetz/gruvbox/releases)

---

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