# Catppuccin for Zed: four pastel flavors and a generated accent set

> catppuccin/zed is a Zed theme extension that ships the four Catppuccin flavors, Latte, Frappe, Macchiato and Mocha, with accent variants that are generated from a single template and installed as JSON files. It is a small repository with a clear build pipeline, and it is worth understanding how it is generated if you intend to tweak it.

**catppuccin/zed** — 🦀 Soothing pastel theme for Zed

- Repository: https://github.com/catppuccin/zed
- Stars: 928 · Forks: 39
- Language: Just
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/catppuccin-zed

## A theme extension, and the unusual thing about its primary language

catppuccin/zed is a theme for the Zed editor, published as a Zed extension rather than as a settings file you copy around. The repository carries an extension.toml, a themes directory, a template file called zed.tera, a justfile, and asset images for the previews.

The detail that tells you how the project is built is the primary language, which is Just. Just is a command runner, and the justfile in this repository is a small set of recipes that wrap the theme generator. In other words, there is no hand written theme file in this repository. The colours come out of a template, and the template language for that is the one you do not see in the file list, because zed.tera is a template rather than a program.

The theme itself is described as a soothing pastel theme, and it covers the four standard Catppuccin flavors with preview images for each: Latte, Frappe, Macchiato and Mocha. The accent variants are the part that makes it more than four static colour schemes, and they are handled separately from the extension install.

The licence is MIT, and the copyright line reads 2021-present for the Catppuccin organisation, which gives a sense of how long the palette has been in use even though this particular extension is younger.

## Installing through the Zed extension system takes four steps

The usage instructions are short because Zed handles the delivery.

You open Zed, open the command palette with the keyboard shortcut the instructions give, and enter zed: extensions. You search for the Catppuccin extension and install it. Then you enter theme selector: toggle in the command palette and pick the Catppuccin theme in your preferred flavor from the dropdown.

That last step is where the naming matters, and it comes up again later. Zed lists the installed theme by its full name, flavor and accent combined, and the dropdown is the authoritative list of what you can select. Anything you write by hand, in a settings file or in a configuration elsewhere, has to match that name exactly.

The project also links a Catppuccin Icon Pack in the Zed extension list, and the note in the usage section points to it directly. Icons and colours are separate extensions in Zed, so a user who wants the full look installs two things, and this repository is only responsible for the colour half.

For a user, this path is close to zero maintenance. The extension is updated through Zed itself, and a new upstream release brings a new flavor or a colour correction without the user touching a file.

## Accent variants are JSON files you drop into the Zed config folder

The accents are a manual path, and the instructions are explicit about it. You download the JSON file of your preferred accent from the latest GitHub release, you create a themes subfolder inside the directory of your Zed configuration file, which is typically ~/.config/zed/, you move the downloaded file into that subfolder, you restart Zed, and then you use theme selector: toggle to select the new flavor and accent combination from the dropdown.

Two things follow from that sequence. The first is that the accent file is a plain theme JSON, so the same file could be inspected, edited or committed to your own dotfiles repository if you want your colours to survive a reinstall. The second is that Zed has to be restarted before the file is picked up, which is a different update cycle from the extension, and it is the sort of detail that makes people believe their change did not work.

The accents are also how the project publishes its themed output. The justfile has a recipe for generating all flavors for a GitHub release, and the release recipe uploads the theme JSON files, so the manual install path and the published assets come from the same generator.

## Theme overrides need the exact theme name, accents and No Italics included

Customisation goes through Zed's own theme overrides in settings.json. The example in the project changes the variable token to pink in Macchiato.

```json
{
  "theme_overrides": {
    "Catppuccin Macchiato": {
      "syntax": {
        "variable": {
          "color": "#f5bde6"
        }
      }
    }
  }
}
```

The merge instruction is the part people miss. You merge this into your existing settings, and the key has to be the exact theme name shown in the theme selector, including any accent suffix or the No Italics suffix.

The documentation also handles the most common failure, where a token refuses to change. The instruction is to focus the editor and run dev: open highlights tree view to identify the syntax rule the token uses. In other words, an override that appears to be ignored is usually an override on the wrong token, and the highlights tree shows which rule is actually in play.

The practical takeaway is that the accent and No Italics suffixes multiply the number of possible theme names, and each one needs its own override entry. A user who wants one pink variable in all four flavors writes four blocks.

## Whiskers generates every theme from one template

Building the themes locally requires Whiskers, which the project describes as Catppuccin's in-house theme generator. Once it is installed, a single command generates all of the themes into the themes directory.

```bash
whiskers zed.tera
```

The justfile wraps that with the same command under an all recipe, and offers a build recipe for a single flavor, defaulting to mauve, that passes an override for the accent.

```bash
brew install catppuccin/tap/whiskers
```

```bash
whiskers zed.tera --overrides '{"accent": ["{{ flavor }}"]}'
```

The brew line is in a setup recipe marked for macOS, so the documented installation path for the generator is the Homebrew tap, and the README asks that Whiskers be installed first if you want to work on the themes.

Testing is done inside Zed itself. You install the extension in development mode with zed: install dev extension, select this repository, and refresh with zed: reload extensions. If a change does not show up immediately, the instructions say that workspace: reload may be needed, and they link the Zed extension development documentation for the details.

## Releases are signed tags plus uploaded theme JSON

The release recipe in the justfile shows how the published assets are produced. It builds all the flavors first, then creates a signed git tag and pushes it, then creates a GitHub release with the generated theme files attached.

```bash
git tag -s "{{ tag }}" -m "{{ tag }}"
git push origin "{{ tag }}"
gh release create "{{ tag }}" themes/*.json --title "{{ tag }}" --generate-notes
```

The signed tag matters more than it looks. Because the accent files are distributed from the GitHub release, the signature is what tells a user that the JSON they are about to drop into their editor configuration came from the maintainers.

The generated notes in that command mean the release description is written by the tooling rather than by hand, which is a hint about the project's rhythm: the theme set is generated, and the release is a packaging step.

There is also a clean recipe that removes the generated theme files, and a group of act recipes that run GitHub Actions workflows locally in containers, with the ubuntu 24.04 runner mapped to a specific image and the GitHub token taken from the local gh authentication. That is how a contributor checks a workflow change before pushing it.

## Version 0.2.27 and a repository that keeps its tooling in view

The releases are frequent and small. The latest tag is v0.2.27 from 2026-09-18, with v0.2.26 from 2026-09-07 and v0.2.25 from 2026-01-23 before it, and the last push was on 2026-09-18. The gap between January and September is where a small theme project spends its time, and the last two months show what an active period looks like here.

The repository is organised like an infrastructure project rather than a hand maintained theme. It has a justfile for every task, a .github directory, a .zed directory, an editorconfig, a renovate.json for automated dependency updates, and both AGENTS.md and CLAUDE.md files, which is a sign that contributors are expected to work with coding assistants on the templates.

The credit section names tecandrew, and the copyright belongs to the Catppuccin organisation. The theme itself is one artefact in a wider palette that also covers icon packs, and the same generator approach is used across the Catppuccin projects, which is why a change in the palette propagates here as a regenerated set of JSON files rather than as hand edited colours.

For a user, none of this matters beyond the update cadence. For someone who wants to contribute, the pipeline is short enough to read end to end in one sitting.

## Conclusion

Adopt Catppuccin for Zed if you want the four standard flavors installed through the extension system and expect the theme to track upstream releases without any manual work. Do not adopt it as your only route to those colours, because accent variants still have to be fetched from a GitHub release and dropped into the Zed configuration directory by hand, and a Zed restart is required before they appear. Before you change a colour, check the exact theme name in the theme selector, since the override key has to match it including any accent or No Italics suffix, and if a token refuses to change, run dev: open highlights tree view to find the rule that owns it. If you want to build the themes yourself, install Whiskers, run whiskers zed.tera, and load the result with zed: install dev extension.

## FAQ

### How do I install the Catppuccin theme in Zed?

Open the command palette, enter zed: extensions, search for the Catppuccin extension and install it, then enter theme selector: toggle and pick the Catppuccin theme in your preferred flavor. There is also a separate Catppuccin Icon Pack extension if you want matching icons.

### How do I install a Catppuccin accent variant for Zed?

Download the JSON file of the accent from the latest GitHub release, create a themes subfolder inside your Zed configuration directory, typically ~/.config/zed/, move the file there, restart Zed, and then select the flavor and accent combination with theme selector: toggle.

### Why does my theme override in settings.json not change a token?

The override key has to match the exact theme name shown in the theme selector, including any accent or No Italics suffix, and the token has to be the one the syntax rule actually uses. The project suggests focusing the editor and running dev: open highlights tree view to identify the rule in play.

### How do I build the Catppuccin Zed themes myself?

Install Whiskers, Catppuccin's theme generator, then run whiskers zed.tera to generate all themes into the themes directory. The justfile wraps the same command with an all recipe and a build recipe for a single flavor with an accent override, and a clean recipe that removes the generated files.

### What licence is the Catppuccin Zed theme released under?

The licence field on the repository says MIT, with the licence text in the LICENSE file at the repository root. The copyright is held by the Catppuccin organisation from 2021 onward.

## Sources

- [catppuccin/zed on GitHub](https://github.com/catppuccin/zed)
- [Issues](https://github.com/catppuccin/zed/issues)
- [License: MIT](https://github.com/catppuccin/zed/blob/main/LICENSE)
- [README](https://github.com/catppuccin/zed/blob/main/README.md)
- [Releases](https://github.com/catppuccin/zed/releases)

---

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