emacs-theme-gruvbox: six contrast variants of one retro colour scheme

A Vim scheme that was ported, not designed for Emacs

Gruvbox is a retro groove color scheme for Emacs. It is a port of the Vim version originally by Pavel Pertsev, found in the gruvbox repository, and the homepage of this project points at that Vim project.

That origin explains a lot about the result. The palette was designed for Vim, where the scheme has to work across a small set of syntax groups, and porting it to Emacs means mapping that fixed palette onto the much larger and messier face system Emacs has. The result is a port in the sense that the colours come from the original, and the work is in the mapping.

The palette section of the readme is worth noting for what it implies about the effort. There are separate palette images for the dark tones, the mid tones, the light tones, the bright colours, the neutral colours, the faded colours, the dark notes, the solo notes and the rainbow delimiters. That is a lot of colour roles to fill, and the images are the reference for what each one is for.

One detail is stated plainly and matters if you are comparing the light and dark themes: the dark and light tones are transposed in the light versions. So the light themes are not a naive inversion of the dark ones, which is the usual source of the fact that a light variant of a dark theme looks wrong.

The licence is MIT, and the copyright header in the readme shows four contributors, with copyright years running from 2013 to 2018.

Six themes, one palette, and the choice you have to make first

The theme versions section is the part that requires a decision rather than a reading.

There are six. Gruvbox Dark Medium, also known as the default, with theme name gruvbox-dark-medium. Gruvbox Dark Soft at gruvbox-dark-soft. Gruvbox Dark Hard at gruvbox-dark-hard. Then the light trio: Gruvbox Light Medium at gruvbox-light-medium, Gruvbox Light Soft at gruvbox-light-soft, and Gruvbox Light Hard at gruvbox-light-hard.

The naming makes the axis explicit. Soft is the gentlest, Medium is the middle, and Hard is the most contrasted. So the choice is a contrast choice within a hue family, twice over, once for dark and once for light.

The Medium variant is the default in the sense that the readme calls it the default, and it is the one a first-time user will end up with if they do nothing clever. The Hard variants push the foreground and background apart more, which matters on a dim screen or with an older panel, and the Soft variants pull them together, which some people find calmer for long sessions.

The tree at the repository root shows the packaging. There is a gruvbox.el, a gruvbox-theme.el, and then a separate file per variant with names like gruvbox-dark-hard-theme.el, gruvbox-dark-medium-theme.el and gruvbox-light-soft-theme.el. Six variants, six files, plus the shared base.

This is why the theme name matters when you install it. You are not installing a single gruvbox theme, you are choosing one of six, and the choice is a visual one that is not obvious from a screenshot at small size.

Installing from ELPA or MELPA, and the safe-theme step people forget

The recommended way to install the Gruvbox theme is with NonGNU ELPA or MELPA, and the version of gruvbox-theme there will always be up-to-date.

NonGNU ELPA is the path the readme leads with. This archive is enabled by default in Emacs 28 or later, so the install is a single interactive command:

M-x package-install <RET> gruvbox-theme

The fact that the archive is on by default from Emacs 28 onward is what makes this the low friction route for current users.

MELPA is the alternative, for Emacs 25 users or anyone with a recent version of package.el, and the readme links the MELPA repository entry for the theme.

Manual installation is also covered: clone the repository and add it to your Emacs load-path and custom-theme-path.

Then there is the step that catches people out, and it is a step of the theme system rather than of this theme. Emacs requires themes to be flagged as safe, so you use M-x load-theme to load and enable the gruvbox themes. Without the safe flag, Emacs will refuse to load the theme, and the symptom is a file prompt or a silent no-op rather than a colour scheme.

So the whole install is two interactive commands on a modern Emacs: install from package, then load the theme by name, with the variant name spelled out exactly as in the version list, for example gruvbox-dark-medium.

The mode support list, which is the real work of a port

The theme contains custom support for a long list of features and plugins, and that list is the most informative part of the readme for anyone deciding whether to use it.

The packages covered include Ag.el, Ace jump, Ace window, Anzu, Auto-dim-other-buffers, Circe, Comint and the like, Company, diff-hl, Diffs, Dired+, Diredfl, Elfeed, ElScreen, ERC, Eshell, Flycheck, Gnus, Helm, Highlight Indent, Hydra, Ivy, Js2-mode, LaTeX, Linum-relative, Magit, Markdown, Message, Neotree, Orderless, Org, Popup, Proof General, RainbowDelimiters, Shell script, Smart modeline, Smartparens, Term, Tool Tips, Undo Tree, Whitespace-mode and Widget Faces.

That is a catalogue of the Emacs ecosystem as it looked, and reading it tells you two things. First, the theme has been maintained against a lot of packages over the years, which is the work that a palette port does not do for you. Second, the list is historical: it names packages and features that were current at particular moments, and it does not include many of the things a new Emacs configuration uses.

A few entries are worth singling out because they are not packages but Emacs features, and they are where a theme either works properly or shows its seams. Smart modeline, Whitespace-mode, Tool Tips, Highlight Indent, Diffs and Comint are all places where the default faces are visible, and a scheme that only covers syntax highlighting looks unfinished in them.

Widget Faces and the rainbow delimiters palette entry point at the same kind of work. RainbowDelimiters draws matching pairs of brackets in colour, and getting those to work with a fixed palette means choosing which palette role serves as the counterpart colour, which is exactly the kind of decision a port makes once and you inherit.

What the state of the project means for a theme you never touch again

The maintenance picture here is unusual, and it deserves a straight assessment rather than a hedge.

The recent releases are 1.30.2 on 2025-01-07, 1.30.0 on 2022-08-13, and 1.28.0 on 2019-04-25. So the tagged releases are old, with a three year gap in the middle of that sequence. The repository is not archived and the last push was on 2026-09-11, so commits do land.

For a colour theme this matters less than it would for a library, and here is the honest reason. A theme is a file of face definitions. If your Emacs configuration and the packages you use keep working, the theme keeps working, because nothing about it needs to change when the packages change. New packages, new major modes and new Emacs versions introduce new face names, and a theme that has not been updated will simply not colour them, leaving them in the default colour, which in a dark theme is often the wrong one.

So the practical failure mode of an unrefreshed theme is not breakage but partial coverage. A new mode appears and renders with default colours that clash with the palette, and you either find a face to override yourself or you live with it. That is a small annoyance rather than a bug, but it is an annoyance that accumulates.

There is also the version question that a theme forces on you. Since you enable a specific theme name, and the six variants are separate, an upgrade path means choosing the same variant in the new version and re-checking that it looks the way you remember. Themes have no semantic versioning story in practice, only a sequence of point releases that add faces.

For an organisation standardising on a theme across a team, the stability is an argument in favour. For an individual who chases new packages, the coverage gap is the cost.

Against the Vim original, and against a generic Emacs theme

Two comparisons make the trade legible.

The first is against just using the Vim version and not porting it at all. The difference in approach is that the Vim scheme is a set of syntax groups, while Emacs has a face system that covers far more of the interface, and the port is the work of filling in those faces with a coherent mapping. If you live in Emacs and Vim on the side, having the same palette in both is a coherence win that is hard to get any other way, since the alternative is hand tuning a second palette.

The second is against a generic Emacs theme, whether that is the built-in default or one of the many modern ones. A generic theme aims to be acceptable everywhere and is therefore conservative in its contrasts and conservative in its colour choices. Gruvbox is opinionated, with a warm retro palette, and it goes to the trouble of defining specific faces for a long list of packages rather than leaving them to inheritance.

The trade is that opinionation has a cost. A port inherits the original design decisions, including the ones you would have made differently, and you cannot change a single hue without forking the theme. A generic theme lets you override what you need and inherits the rest.

The practical decision is less about feature lists and more about what your day looks like. If you already use Gruvbox in Vim, the question is settled. If you are choosing a scheme for the first time, the six variants and the long package list are a good sign of care, and the age of the releases is a fair question to ask about the packages you actually run.

Editorial conclusion

Adopt emacs-theme-gruvbox if you already use the Gruvbox scheme in Vim and want the same palette in Emacs, and you prefer a theme with per-package faces tuned rather than a generic one. Skip it if you want a theme that tracks new Emacs and new packages, since the newest tagged release is 1.30.2 from 2025-01-07 and the last push was on 2026-09-11. Verify first which of the six variants you actually want, because switching between them later changes the whole look, and check that the packages you use are in the mode support list before you rely on their highlighting.

Frequently asked questions

Official sources

1. greduan/emacs-theme-gruvbox on GitHub
2. License: MIT
3. Project website
4. README
5. Releases