mbadolato/iTerm2-Color-Schemes: 450+ Terminal Themes and the Ports That Ship With Them

The problem is port drift, not a shortage of themes

Terminal palettes are 16 ANSI slots plus a handful of named colors: background, foreground, cursor, cursor text, selection and selection text. The README's template placeholder list names exactly those, from {{ Background_Color }} through {{ Ansi_8_Color }}. Every terminal emulator stores them in a different file format, so a palette that looks right in iTerm2 has to be retyped by hand for Kitty, Alacritty, Windows Terminal or Konsole. That retyping is where colors drift.

This repository treats the iTerm2 file as the source and everything else as generated output. The top-level directory listing shows the scale of that bet: alacritty/, ghostty/, kitty/, konsole/, putty/, windowsterminal/, xfce4terminal/, xrdb/, vim/, vscode/ and more, each a port target. The audience is anyone who moves between terminals and wants the same palette on both sides, plus theme authors who would rather write one YAML file than eleven configs.

How gen.py turns one .itermcolors file into many formats

Two source formats feed the generator. A theme can live in schemes/ as a .itermcolors plist, or in yaml/ as a YAML file. The README describes the YAML format as an extension of the format used by the Gogh project, which matters if you already have Gogh themes: the conversion is closer to a copy than a rewrite.

Generation is template-driven. Each port target holds a config file in which the real colors have been replaced with placeholders such as {{ Ansi_1_Color }}. Running the generator substitutes values and writes the output file for that target. Adding support for a new terminal means taking one of its config files, swapping the literal colors for placeholders, and leaving it in the tree; the README documents this as the "How to add new template" path. The generator itself runs from tools/, which is why the Makefile, the Dockerfile and the README examples all cd into that directory before invoking python -m gen or python gen.py.

One detail in the README is worth reading twice. After generation, gen.py may adjust colors to meet a minimum contrast threshold of 1.75:1. A generated port is therefore not always a byte-for-byte copy of the source palette. If you are matching a theme to a design system with fixed hex values, that adjustment is a behavior you need to know about before you diff the output.

Installing a scheme in iTerm2 and importing it from the shell

The README gives three installation routes: the ⌘+i keyboard shortcut, the iTerm2 preferences menu under Profiles > Colors > Color Presets > Import, and a Bash script. The script is the one worth scripting around, because it takes scheme names or file paths and can import in bulk.

Run it from the repository root. Passing schemes/* imports everything; the -v flag turns on verbose mode. The README notes that quotations are needed for schemes with spaces in the name.

# Import all color schemes
tools/import-scheme.sh schemes/*

# Import specific schemes by file path or by name
tools/import-scheme.sh 'schemes/SpaceGray Eighties.itermcolors'
tools/import-scheme.sh 'SpaceGray Eighties'
tools/import-scheme.sh Molokai 'SpaceGray Eighties'

After importing, the README states you must quit iTerm2 to reload the configuration file. Restarting the app, not just opening a new window, is the step people skip when a scheme does not appear.

To generate ports for a theme you are working on, the README gives this command, run from the repository root:

python3 tools/gen.py -s "Your Theme Name"

The -s flag selects by scheme name, and the README instructs quoting names that contain spaces. If you are contributing, the README also shows the screenshot step, which writes images where they are missing:

pushd tools && python3 -m screenshot_gen && popd

If oxipng or zopflipng is installed, the README says the generated screenshot will be optimized.

The WCAG check is a signal, not a gate

The repository ships tools/wcag_check.py, run as python3 tools/wcag_check.py -s "Your Theme Name". The README is explicit about two constraints that change how you should read its output.

First, the check covers .itermcolors files only. YAML themes must be generated before they can be checked. If your contribution lives in yaml/, the checker will not see it until generation has produced an .itermcolors file.

Second, and more important, the README states that failing checks are OK. The generator may adjust colors during generation to meet the minimum contrast threshold of 1.75:1. A 1.75:1 ratio is well below the 4.5:1 that WCAG AA asks for body text. So the checker is reporting against the project's own floor, not against an accessibility standard. If you pick a scheme for a light background and your editor renders dim comments, a passing check here tells you very little. Run the checker, then look at the scheme on your actual background.

Where the collection model breaks down

A repository that accepts themes from contributors inherits whatever quality those contributions have. The README's contribution path asks for a pull request, a README.md update with a theme and screenshot, and an optional CREDITS.md entry. There is no stated review criterion for aesthetic consistency or contrast beyond the WCAG script and its 1.75:1 floor. With more than 450 schemes in the collection, the practical result is a wide catalog rather than a curated one. If you want ten palettes that all meet a real contrast bar, this repository is the wrong starting point: you will spend more time filtering than you would picking from a smaller set.

The generator also assumes you are comfortable with its toolchain. The README's prerequisites ask for pyenv, a pyenv install inside the project folder to pick up the version in .python-version, and pip install -r requirements.txt. requirements.txt pins Jinja2, pillow, pyyaml, rich, numpy and unidecode, and the Dockerfile builds on python:3.11-slim. If you only want one theme file, none of this matters, because the .itermcolors files are committed directly and can be imported without running any Python. The build pipeline is for contributors and for anyone regenerating ports, not for consumers.

Licensing deserves a look before you redistribute. The repository's license is recorded as NOASSERTION, which means the license could not be classified automatically. The repository does contain a LICENSE file at the top level, so the terms exist; read that file rather than relying on a classifier. Nothing here is legal advice, and theme collections that aggregate third-party contributions often carry per-scheme provenance in CREDITS.md.

How it compares with Gogh and hand-written dotfiles

The closest alternative named in the README is Gogh, the project whose YAML format this repository extends. The difference is the direction of the pipeline. Gogh is built around installing themes into a terminal from its own catalog. This repository treats iTerm2 as the origin format and generates outward, which means the .itermcolors files are the canonical artifacts and the YAML layer is the contribution path for themes that arrive from elsewhere. If you want a one-command installer for a specific terminal, Gogh's model fits better. If you want a palette that exists in iTerm2, Kitty and Windows Terminal at the same time, this repository's generator is the mechanism that gets you there.

The other alternative is maintaining dotfiles by hand. That works when you use one terminal. The moment you keep a Kitty config, an Alacritty config and a Windows Terminal JSON profile in sync, hand-editing means three places to change and three chances to mistype a hex value. The generator collapses that to one source file plus a command. The cost is a Python environment and a build step in your workflow, which is a real cost if you change palettes once a year.

Frequently asked questions

The FAQ entries below cover the questions people actually search for around this repository. Answers are limited to what the README, the repository layout and the release notes state.

Editorial conclusion

Adopt it if you want one source of truth for terminal palettes across several emulators, or if you are contributing a theme and want ports generated rather than hand-written. Do not adopt it if you need a curated, contrast-guaranteed set, or if you expect the repository to validate a theme you submit: the README states failing WCAG checks are acceptable and gen.py may shift colors to reach a 1.75:1 minimum. Before importing anything, open tools/wcag_check.py against the scheme you plan to use on a light background, and run tools/import-scheme.sh on a single file first to confirm it lands in your iTerm2 profile.

Frequently asked questions

Official sources

1. Issues
2. mbadolato/iTerm2-Color-Schemes on GitHub
3. Project website
4. README
5. Releases