Catppuccin VS Code Setup: Install, Choose a Flavor, and Customize

Catppuccin for VS Code is more than a dark editor background with purple syntax. The official extension gives you four complete color themes, a configurable accent, several workbench layouts, bracket-color options, and matching file icons. The useful part is that you can start with two clicks and only open settings.json when you want something specific.

This guide installs the official Catppuccin extension, helps you choose between Latte, Frappé, Macchiato, and Mocha, and builds a clean configuration without replacing the palette one hex value at a time.

Install the official Catppuccin extension

1. Open Visual Studio Code.
2. Open Extensions with Ctrl+Shift+X on Windows or Linux, or Cmd+Shift+X on macOS.
3. Search for Catppuccin for VSCode.
4. Choose the extension published by Catppuccin, with extension ID Catppuccin.catppuccin-vsc.
5. Select Install.

You can also install it from the command line:

code --install-extension Catppuccin.catppuccin-vsc

If the code command is unavailable, use the Extensions view instead. On macOS, you can add it to your shell from the Command Palette with Shell Command: Install 'code' command in PATH.

The safest check is the publisher and extension ID, not the icon or the first search result. The canonical listing is the Catppuccin for VSCode Marketplace page, and the source and current option names live in the official GitHub repository.

Activate a Catppuccin flavor

After installation, open the theme picker with Ctrl+K Ctrl+T on Windows or Linux, or Cmd+K Cmd+T on macOS. You can also open the Command Palette and run Preferences: Color Theme. Move through the list to preview each flavor, then press Enter to keep one.

For most dark-theme users, Mocha is the obvious first trial. Give it a real coding session, not a ten-second preview. If comments, line numbers, inactive tabs, or the Explorer tree disappear when your display brightness drops, switch to Macchiato before editing individual colors. Frappé is the softer choice for a bright office. Latte is a first-class light theme rather than a token daytime variant.

VS Code saves the active theme as a normal setting. The equivalent JSON is:

{
  "workbench.colorTheme": "Catppuccin Mocha"
}

A practical Catppuccin settings.json

Open the Command Palette and run Preferences: Open User Settings (JSON). Add the options below inside the existing top-level object. Do not paste a second pair of outer braces into a file that already contains settings.

{
  "workbench.colorTheme": "Catppuccin Mocha",
  "catppuccin.accentColor": "mauve",
  "catppuccin.boldKeywords": true,
  "catppuccin.italicKeywords": true,
  "catppuccin.italicComments": true,
  "catppuccin.workbenchMode": "default",
  "catppuccin.bracketMode": "rainbow",
  "editor.semanticHighlighting.enabled": true,
  "terminal.integrated.minimumContrastRatio": 1,
  "window.titleBarStyle": "custom"
}

This is close to the extension's intended presentation. Semantic highlighting lets supported language services distinguish symbols more precisely than basic TextMate scopes. Setting the integrated terminal's minimum contrast ratio to 1 prevents VS Code from automatically altering terminal colors, so the terminal stays faithful to the Catppuccin palette. That value is a color-fidelity choice, not an accessibility upgrade; increase it again if terminal text becomes difficult to read.

The custom title bar allows workbench colors to reach the title bar instead of leaving it to the operating system. If you prefer a native title bar, omit that line.

Choose an accent color

The default accent is Mauve, which is why purple selections and highlights are strongly associated with Catppuccin. The catppuccin.accentColor setting can use any named Catppuccin color. Good alternatives include blue, lavender, pink, peach, green, and teal.

{
  "catppuccin.accentColor": "blue"
}

The accent changes selected and emphasized interface elements; it does not remap the entire syntax palette. Pick it for cursor-level recognition and UI balance, not because you expect every Mauve token to turn Blue.

Control italics and bold syntax

Catppuccin uses font style as well as color to separate roles. Italic comments feel soft and deliberately secondary. Italic or bold keywords make control flow easier to scan. Whether that helps depends heavily on the font: some programming fonts have a carefully drawn italic face, while others simply lean the regular letters.

For a quieter editor, disable the style options without touching the colors:

{
  "catppuccin.boldKeywords": false,
  "catppuccin.italicKeywords": false,
  "catppuccin.italicComments": false
}

If this appears to do nothing for one language, another extension or a semantic-token rule may be taking priority. Use Developer: Inspect Editor Tokens and Scopes on the affected token before adding broad overrides.

Default, flat, or minimal workbench

catppuccin.workbenchMode controls how many background layers VS Code uses:

• default uses three shades. In Mocha, the editor uses Base #1e1e2e, the sidebar uses Mantle #181825, and the outer chrome uses Crust #11111b.
• flat reduces the workbench to two shades, giving the sidebar and surrounding bars a closer relationship.
• minimal uses one background shade across the workbench.

{
  "catppuccin.workbenchMode": "flat"
}

Default has the clearest hierarchy and looks most recognizably Catppuccin. Flat works well on smaller displays where the Activity Bar, sidebar, and editor otherwise feel like nested boxes. Minimal is clean, but the Explorer can become harder to locate at a glance.

Tune bracket colors

The catppuccin.bracketMode option changes paired-bracket coloring:

• rainbow uses Red, Peach, Yellow, Green, Blue, and Mauve.
• dimmed keeps that sequence with quieter colors.
• monochromatic uses neutral Catppuccin surface and subtext colors.
• neovim follows the sequence used by the related Neovim rainbow-bracket integration.

Rainbow is easiest to parse in nested JavaScript, TypeScript, JSON, and Lisp-style code. Dimmed is a better first adjustment if brackets pull attention away from the code. Monochromatic is for people who want nesting help without another row of syntax colors.

Add the matching Catppuccin icon pack

The color theme does not automatically change file icons. Install the separate Catppuccin Icons extension, then run Preferences: File Icon Theme and select Catppuccin.

The icon pack is optional. It makes the Explorer more cohesive, but combining the color theme with Material Icon Theme, Symbols, or VS Code's Seti icons does not break anything. Keep the icon set that helps you identify files fastest.

User settings or workspace settings?

A theme selected normally is stored in User settings and follows you across projects. VS Code can also store workbench.colorTheme in a project's .vscode/settings.json. That is useful when you want a visual warning that you have switched repositories—for example, Latte for documentation and Mocha for application code.

Do not commit personal Catppuccin preferences to a shared repository unless the team wants them. Accent color, italics, and workbench mode are usually user choices. Keep them in User settings and let Settings Sync carry them between your machines.

Customize colors without fighting the extension

First use Catppuccin's own settings. The extension supports palette-level overrides through catppuccin.colorOverrides and interface mappings through catppuccin.customUIColors. These understand flavor names and Catppuccin color names, so they are easier to maintain than a long list of raw VS Code colors.

This example changes only Mocha's three main background layers:

{
  "catppuccin.colorOverrides": {
    "mocha": {
      "base": "#191926",
      "mantle": "#15151f",
      "crust": "#101018"
    }
  }
}

VS Code also supports workbench.colorCustomizations, editor.tokenColorCustomizations, and editor.semanticTokenColorCustomizations. Use those when you need to target a VS Code component or token rather than a Catppuccin palette role. Theme-specific overrides are safer than global ones because they will not leak into another theme later.

Common Catppuccin VS Code problems

The extension is installed, but the editor did not change

Installing a color theme does not always activate it. Run Preferences: Color Theme and select the exact Catppuccin flavor. If a workspace has its own workbench.colorTheme, that setting can override your user-level choice.

The integrated terminal colors look wrong

VS Code may adjust terminal colors to meet its configured contrast threshold. The official Catppuccin recommendation uses "terminal.integrated.minimumContrastRatio": 1 for faithful colors. Also check whether your shell prompt or terminal profile is applying its own palette on top.

Settings show as unknown

Confirm that Catppuccin.catppuccin-vsc is enabled in the current VS Code profile. Remote SSH, Dev Containers, WSL, and separate profiles can have different extension states. Reload the window after enabling or updating the extension.

Comments are too faint in Mocha

Try Macchiato before forcing comments to white. Its lighter background often fixes the practical contrast problem while preserving the palette's hierarchy. You can also disable comment italics if the font's italic strokes look thinner than its regular face.

Syntax colors change between languages

Different language extensions contribute different TextMate scopes and semantic tokens. Keep semantic highlighting enabled, update the language extension, and inspect a problematic token before writing overrides. A color theme cannot make two language grammars expose identical information.

A sensible finished setup

Start with Mocha, Mauve, the default three-layer workbench, rainbow brackets, and semantic highlighting. Add the icon pack only if it improves file recognition. After a day, change one thing: move to Macchiato if the background is too deep, switch brackets to dimmed if nesting colors are loud, or turn off font styles if italics slow you down.

If you are still deciding whether the soft pastel system suits you, read Tokyo Night vs Catppuccin. For the larger story behind the palette and its many ports, see the Catppuccin color ecosystem. Both links point to published Petit Keycaps articles.

Once the editor feels right, stop tuning. A good theme should make the window familiar, keep the code readable, and then get out of the way.

Installation steps and setting names were checked against the official Catppuccin for VSCode repository and Visual Studio Code theme documentation.