# alacritty-theme: a color scheme collection for Alacritty, installed by import

> The alacritty/alacritty-theme repository collects Alacritty color schemes as individual TOML files that you pull in with an import line. This covers how the import mechanism works, what the README does not document, and where a different tool fits better.

**alacritty/alacritty-theme** — Collection of Alacritty color schemes

- Repository: https://github.com/alacritty/alacritty-theme
- Stars: 2,921 · Forks: 218
- Language: Shell
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/alacritty-alacritty-theme

## What alacritty-theme actually is

This repository is a collection of color schemes for the Alacritty terminal emulator, nothing more. There is no binary, no daemon and no runtime. The top level holds LICENSE, README.md, images/, print_colors.sh and themes/. The themes/ directory is where the schemes live, one file per scheme, and images/ holds the screenshots the README embeds in its table so you can see a scheme before using it.

The audience is narrow by design: people who already run Alacritty and want a scheme they can reference by path instead of transcribing sixteen color values by hand. If you do not run Alacritty, the files are inert. The README's table lists names such as acme, afterglow, alabaster, aura, ayu_dark, ayu_light, ayu_mirage, azu, baitong, base16_default_dark, blood_moon, bluish, breeze, campbell, carbonfox and the catppuccin variants, each with a source link to the upstream project the colors came from. That attribution column is the most informative part of the README: it tells you this is a distribution point for schemes authored elsewhere, not a single design system.

## How the import mechanism works

Alacritty reads a TOML configuration file, and that file supports an import key that pulls in another file. The alacritty-theme README uses exactly that: you keep the cloned repository somewhere on disk and point an import at one file inside themes/. Alacritty then merges that file's contents, which are the color definitions, into your running configuration.

This is the whole architecture. There is no build step, no generation script for the schemes themselves, and no registry the terminal queries at startup. The consequence is that the scheme is only as good as the file you imported. If a theme file is malformed TOML, or if it defines a key your Alacritty version does not recognize, the failure surfaces when Alacritty loads the config, not before. The repository gives you files; Alacritty does the parsing and the merging.

The manual path the README describes is the same data with the import removed: copy the entire content of the theme into the root level of alacritty.toml. That works, but it means the colors are now yours to maintain, and updating the scheme means re-copying. The import path keeps the file separate so a git pull in the clone updates every scheme at once.

## Installing alacritty-theme and applying a first scheme

The README's install instructions assume a Linux config layout and clone the repository into the Alacritty themes directory. The comment in the README notes it uses Alacritty's default Linux config directory as the storage location.

```bash
mkdir -p ~/.config/alacritty/themes
git clone https://github.com/alacritty/alacritty-theme ~/.config/alacritty/themes
```

After the clone, the scheme files sit under ~/.config/alacritty/themes/themes/, because the repository itself contains a themes/ directory. That doubled path is the most common place to get the import wrong.

Next, add the import to your alacritty.toml, replacing the placeholder with the scheme name you want. The README writes it with a tilde path and a TOML array:

```toml
[general]
import = [
    "~/.config/alacritty/themes/themes/{theme}.toml"
]
```

So for the gruvbox scheme the line becomes "~/.config/alacritty/themes/themes/gruvbox.toml". Save the file and Alacritty picks up the colors on its next config load. To change schemes later, edit that one filename and reload; you do not touch the color values. If you prefer the manual route, the README says to copy the entire content of the theme into the root level of your configuration file, which works but freezes the scheme in place.

## Where the documentation goes quiet

The README documents installation and lists schemes. It does not document what happens when an import path is wrong, whether Alacritty falls back to its built-in colors or refuses to start, and it does not describe a reload or hot-swap workflow beyond editing the config. There is no rollback section. If a scheme renders badly against your font or your terminal background, the README offers no troubleshooting path other than choosing a different file.

Windows users get no dedicated instructions. The README's clone target is a Linux path, and the import example uses a tilde. Alacritty on Windows uses a different config location, and the README does not spell out what to substitute. You can infer it from Alacritty's own documentation, but this repository does not carry that mapping, so treat the Windows story as something you assemble yourself.

The print_colors.sh script at the top level is the one piece of tooling here, and the README does not explain how to use it. Its name suggests it prints the color set, which is useful for checking a scheme in a terminal, but the README gives no invocation example, so you are reading the script to find out.

## The maintenance question and the licence

The repository is not archived, and the last push was on 2026-09-11, which puts it well inside the window where calling it current is defensible. There are no retrieved releases, so there is no versioned artifact to pin. Your upgrade path is git pull in the clone, which updates every scheme file at once. Because the schemes are imported by path rather than vendored into your config, a pull can change the colors you see without you editing anything. That is the cost of the import approach: convenience on update, surprise on update.

The LICENSE file is Apache-2.0 at the repository level. The README's table, however, links each scheme to its upstream source, and those upstreams carry their own terms. Apache-2.0 on this repository does not automatically relicense a scheme whose colors come from a project under a different licence. If you are redistributing a scheme rather than using it locally, check the source link in the table row for that scheme. This is a factual observation about the layout, not legal advice.

## When a switcher or a port is the better tool

alacritty-theme gives you files and an import line. It does not give you a picker. If you want to browse schemes interactively, preview them, and switch without editing TOML by hand, a theme switcher utility is the different approach: it typically enumerates available schemes and rewrites your config for you. The trade-off is that you now depend on a second tool tracking Alacritty's config format, and the switcher's scheme list may lag the upstream collection.

If you do not run Alacritty at all, the correct alternative is the port for your terminal. The catppuccin project, for example, maintains its own Alacritty port, which the README lists as the source for the catppuccin_frappe, catppuccin_latte and catppuccin_macchiato entries, and catppuccin publishes ports for many other terminals. Going to the upstream project directly gets you its current palette and its own install instructions for your terminal, at the cost of managing one source per scheme instead of one clone for many.

## Conclusion

Use alacritty-theme if you run Alacritty and want a scheme as a file you import rather than colors pasted into your config. Skip it if you need previews, live switching, or support for another terminal. Verify first that your Alacritty version reads the [general] import key the README shows, and that the theme filename you picked exists under themes/ in the clone.

## FAQ

### How do I change the theme in Alacritty with alacritty-theme?

Edit the import path in your alacritty.toml so it points at a different file under themes/, for example changing gruvbox.toml to another scheme name, then let Alacritty reload the config. You do not edit the color values themselves.

### How do I install alacritty-theme?

The README clones the repository into ~/.config/alacritty/themes with git clone, then adds an import entry under [general] in alacritty.toml pointing at the chosen scheme file. The README's example uses Alacritty's default Linux config directory.

### How do I apply an alacritty-theme scheme manually instead of importing it?

The README says to copy the entire content of the theme into the root level of your existing alacritty.toml. The colors then live in your own config rather than in the cloned file.

### What is the best Alacritty theme in alacritty-theme?

The repository does not rank its schemes. The README lists them in a table with screenshot images and a source link per entry, so the comparison it supports is visual, not a recommendation.

## Sources

- [alacritty/alacritty-theme on GitHub](https://github.com/alacritty/alacritty-theme)
- [Issues](https://github.com/alacritty/alacritty-theme/issues)
- [License: Apache-2.0](https://github.com/alacritty/alacritty-theme/blob/master/LICENSE)
- [README](https://github.com/alacritty/alacritty-theme/blob/master/README.md)

---

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