# moe-theme.el: a colourful Emacs theme with light and dark variants

> moe-theme.el is an Emacs Lisp colour theme built for 256-colour terminals, shipped as two variants, moe-dark and moe-light, with a separate theme file for each and a switcher that can follow the time of day. It customises the mode line, title sizes and a long list of major modes.

**kuanyui/moe-theme.el** — A customizable colorful eye-candy theme for Emacser. Moe, moe, kyun!

- Repository: https://github.com/kuanyui/moe-theme.el
- Stars: 774 · Forks: 68
- Language: Emacs Lisp
- License: GPL-3.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/kuanyui-moe-theme-el

## What moe-theme actually is

moe-theme.el is an Emacs colour theme written in Emacs Lisp, described as a customizable colourful theme. The README calls the palette delightful and good-looking, which is the project's own framing, and the top of the file is mostly screenshots: a wide overview image plus a series of dark and light pairs showing different buffer types.

The basics are stated first. It is optimized for terminal 256 colour palettes, and it offers both a dark and a light variant. Everything beyond that is presentation work: carefully considered colours, and a set of customisation hooks.

The repository layout explains an important detail. There is no single theme file. Instead there is moe-theme.el, which the README says is not a theme file but provides the ability for customization, and then moe-dark-theme.el and moe-light-theme.el, which are the actual themes. A separate moe-theme-flavours.el and a moe-theme-switcher.el sit alongside them.

So the theme is really three things: a shared customisation layer, two concrete palettes, and an optional time-based switcher. That structure is why the manual installation adds the directory to custom-theme-load-path rather than to load-path alone.

## The mode list and what full support means here

The README claims full support for a long list of major modes, and the list is the most concrete evidence of how much attention the theme pays to real editing sessions. It covers Diff and EDiff, Dired with its variants, ERC and rcirc for mail, Eshell and ansi-term, Gnus and Message, Helm and ido, Org-mode with Agenda and calfw, Magit with git-commit and git-gutter, markdown-mode, adoc-mode and ReStructuredText-mode, auto-complete-mode and Company, rainbow-delimiters, Swoop, Twittering-mode, undo-tree and Neotree, and the Ruby, Haskell, CPerl, Tuareg and Web modes.

What that means in practice is that the theme does not just recolour faces globally. It sets distinct face colours for diff hunks, for magit status letters, for helm candidates, for company completion, for org headings and for the fringe indicators, which is where most of the perceived polish of a theme comes from.

Syntax highlighting is a separate concern from the theme. The README says Monokai and Tomorrow are optional for syntax-highlighting, or that you can customise it entirely yourself. So the palette of the interface and the palette of the code are two decisions, and the theme ships a sensible default for the first while leaving the second open.

The mode list is also a maintenance obligation, since a theme that names specific packages has to track them, and the last push to the repository was on 2026-08-19 with the default branch named dev.

## Installing from MELPA or by hand

Two installation routes are documented. The first is package.el: moe-theme is available in the MELPA repository, and the README says you can install it with M-x list-packages.

The manual route is to download the archive of moe-theme, or git clone it, to ~/.emacs.d/moe-theme.el and extract it there. Then three lines go into your init file.

```lisp
        (add-to-list 'custom-theme-load-path "~/.emacs.d/moe-theme.el/")
        (add-to-list 'load-path "~/.emacs.d/moe-theme.el/")
        (require 'moe-theme)
```

The first line is the one that matters and the one people forget. custom-theme-load-path is what lets the load-theme machinery find moe-dark-theme and moe-light-theme, while load-path lets the Lisp files themselves be found. Adding only load-path gets you the customisation layer without the themes.

The requirements are modest and stated up front: Emacs 25.3 or above, and a 256-colour terminal or higher. There is no build step, no package to compile and no external dependency, which is typical of a pure Emacs Lisp theme.

Note that the manual path assumes a directory called ~/.emacs.d/moe-theme.el that contains the files, which is an odd name for a directory but is what the README specifies, and the customisation example below uses a different, more conventional path so you can see the pattern.

## Customisation: modeline colour, title sizes and buffer id

The README opens the customisation section with the honest line that it is impossible to satisfy everyone with one fixed theme, and then provides variables instead. The full example in the README is longer than what anyone needs on a first read, so the useful parts are these.

The mode line colour is a single variable with a set of named colours.

```lisp
 (setq moe-theme-modeline-color 'orange)
 ;; (Available colors: blue, orange, green ,magenta, yellow, purple, red, cyan, w/b.)
```

The default is blue, and the available set is fixed at eight named colours plus a white and black option. There is also an interactive command, M-x moe-theme-modeline-select-color, to change it from inside Emacs, and a second one, M-x moe-theme-modeline-random-color, for the whimsical version.

Title resizing works per major mode, with a list of font sizes applied to successive heading levels.

```lisp
        (setq moe-theme-resize-title-markdown '(1.5 1.4 1.3 1.2 1.0 1.0))
        (setq moe-theme-resize-title-org '(1.5 1.4 1.3 1.2 1.1 1.0 1.0 1.0 1.0))
```

The README explains the list lengths: markdown has six items, org has nine, rst has six. A larger number means a larger font, and if you leave the setting nil all titles are the same size. The list for adoc-mode and ReStructuredText-mode is documented separately in the README with the same six-item shape.

One ordering rule is stated and easy to get wrong: these resizing settings must be placed before the call that applies the theme, because applying the theme resets the face sizes. The last line of the example applies the theme, so the setq lines come first by construction.

A third option highlights the buffer id as a decoration, off by default.

```lisp
        (setq moe-theme-highlight-buffer-id t)
```

Finally, the theme is applied by calling one of the two functions.

```lisp
        (moe-light)
```

Or moe-dark for the other variant.

## load-theme, Powerline and the daylight switcher

There is a documented fast path, and it matters because the customisation layer is optional. The README notes that moe-theme.el is not a theme file but provides the ability for customization, so if you want to apply the theme itself with load-theme and no customisations, you can skip the customisation chapter entirely.

```lisp
         (load-theme 'moe-dark t)
         ;;or
         (load-theme 'moe-light t)
```

The second argument set to t tells load-theme to enable the theme without asking for confirmation.

Powerline support exists for anyone running the Powerline mode package. The README says to run powerline-moe-theme if powerline is installed.

```lisp
    (powerline-moe-theme)
```

There is a constraint on ordering here too, stated in the full customisation example: if you want to use powerline, the call to require powerline must come before the call to require moe-theme.

The switcher is the most unusual feature. The package contains rudimentary functionality for swapping between moe-light and moe-dark automatically to match the time of day, enabled with a variable and a latitude and longitude.

```lisp
  (setq calendar-latitude +25
        calendar-longitude +121
```

The coordinates in the example are Taipei. The switcher computes sunrise and sunset for those coordinates, which is why it needs a location rather than a clock time. The switcher lives in its own file, moe-theme-switcher.el, so in a manual installation it has to be required separately, and the README notes that in the manual case you should uncomment the require line for moe-theme-switcher.

## Where moe-theme is the wrong choice

The first limitation is that the palette is a matter of taste and is not a configurable colour system. The mode line colour is one variable with eight named options, and everything else about the colours is fixed in the theme files. A user who needs a specific high-contrast scheme, or who works with a colour vision deficiency and needs the foreground and background pairings to satisfy a contrast ratio, will find that moe-theme gives them no way to express that requirement.

The second is the terminal floor. A 256-colour terminal is the stated requirement, and while 24-bit terminals are common enough now, a theme designed against the 256-colour palette will not use the wider range, so on a modern terminal you get a palette that was constrained by an older hardware limit.

The third is that the two-variant structure adds a step. load-theme works on moe-dark and moe-light directly, but the customisation layer is a separate require, and the ordering rules for powerline and for the resize settings are easy to get wrong. A user who wants Powerline and custom title sizes has to get three requirements and two setq blocks in the right sequence, and the README says as much in a note.

The fourth is maintenance. The default branch is dev, the repository has no published releases on GitHub, and the last push was on 2026-08-19. There is no versioned artefact, so a manual install from a clone can drift from what you tested, and the MELPA package is the only stable way to pin a version.

## Licence, installation footprint and what changes when you customise

The project is under the GPL-3.0 licence, with the LICENSE file at the root of the repository. For a colour theme that only loads Lisp into your own Emacs session, the practical effect is on redistribution rather than on use: a theme you fork and redistribute carries the GPL terms with it, and a theme you keep to yourself raises no question at all.

The footprint is one directory of Lisp files. There are no compiled artefacts, no external packages to install and no build step, and the requirements are Emacs 25.3 or above with a 256-colour terminal. Installing from MELPA also means the update path is the ordinary package.el path, so a new version arrives with the rest of your packages.

What changes when you customise is worth stating plainly, because the customisation layer is a separate file from the themes. Your setq values live in your init file, while the face definitions live in the theme files, so a theme update can change how your overrides are expressed, and a value that you set before applying the theme can be reset by the theme application, which is exactly what the README warns about for the title resizing.

If you rely on several customisations, keeping them in one block after the requires and before the theme call is the arrangement the README itself demonstrates, and it is the arrangement that survives a theme update most often.

## Conclusion

moe-theme.el suits an Emacs user on a 256-colour terminal who wants a finished light and dark palette with sensible defaults for diff, magit, helm, org and company modes, and who is willing to tune a handful of variables. It does not suit a user who needs a specific high-contrast or accessibility palette, since the colour choices are the author's taste rather than a configurable system. Verify your terminal first, at 256 colours or higher, and note that the theme files only appear once you add the directory to custom-theme-load-path.

## FAQ

### How do I install moe-theme.el in Emacs?

Install it from MELPA with M-x list-packages, or copy the repository to ~/.emacs.d/moe-theme.el and add the directory to both custom-theme-load-path and load-path in your init file, then require moe-theme. The README states the requirements as Emacs 25.3 or above and a 256-colour terminal.

### How do I change the mode line colour in moe-theme?

Set the moe-theme-modeline-color variable, whose default is blue and whose available values are blue, orange, green, magenta, yellow, purple, red and cyan plus a white and black option. You can also use M-x moe-theme-modeline-select-color to pick one interactively.

### What is the difference between moe-theme.el and moe-dark-theme.el?

The README states that moe-theme.el is not a theme file but provides the ability for customization of moe-dark-theme and moe-light-theme. If you want only the theme with no customisations, you can skip the customisation layer and use load-theme with moe-dark or moe-light directly.

### Does moe-theme.el support Powerline?

Yes. The README says to run powerline-moe-theme if powerline is installed. The full customisation example also notes that the require for powerline must come before the require for moe-theme.

## Sources

- [Issues](https://github.com/kuanyui/moe-theme.el/issues)
- [kuanyui/moe-theme.el on GitHub](https://github.com/kuanyui/moe-theme.el)
- [License: GPL-3.0](https://github.com/kuanyui/moe-theme.el/blob/dev/LICENSE)
- [README](https://github.com/kuanyui/moe-theme.el/blob/dev/README.md)

---

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