# How to Customize nvm Color Output with NVM_COLORS: A Technical Deep Dive

> Customize nvm color output using NVM_COLORS. This technical deep dive explains how nvm translates codes into ANSI escape sequences via nvm_set_colors and nvm_print_color_code functions in nvm.sh.

- Repository: [nvm.sh/nvm](https://github.com/nvm-sh/nvm)
- Tags: deep-dive
- Published: 2026-02-27

---

**nvm implements color customization through the `NVM_COLORS` environment variable, which validates five single-character codes and translates them into ANSI escape sequences via the `nvm_set_colors` and `nvm_print_color_code` functions in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh).**

The Node Version Manager (nvm) enhances terminal readability by color-coding output for commands like `nvm ls` and `nvm install`. For users who need to adapt nvm's appearance to different terminal themes or accessibility requirements, the project provides the `NVM_COLORS` environment variable. This article examines the complete implementation of this color system in the nvm-sh/nvm repository, tracing how custom palettes flow from environment variables to terminal output.

## How NVM_COLORS Works Under the Hood

The color customization system resides entirely in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) and follows a strict validation and translation pipeline.

### Terminal Capability Detection with nvm_has_colors

Before rendering any colors, nvm verifies that the terminal supports them. The `nvm_has_colors` function (lines 81-86 in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)) checks three conditions: it verifies that `tput` reports at least 8 available colors, confirms that stdout is a TTY, and ensures the user has not set `NVM_NO_COLORS`. If any check fails, nvm outputs plain text regardless of other settings.

### Parsing the Color Palette via nvm_set_colors

When you export a custom `NVM_COLORS` value, the `nvm_set_colors` function (lines 1031-1052 in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)) validates the input strictly. The function requires exactly five characters, each belonging to the allowed set `rRgGbBcCyYmMkKeW`. Each position represents a specific category:

1. **First character**: Installed versions
2. **Second character**: LTS/system versions
3. **Third character**: Current active version
4. **Fourth character**: Not-installed versions
5. **Fifth character**: Default alias

After validation, the function exports the palette as `NVM_COLORS` (lines 1049-1051), making it available for subsequent color lookups.

### The Color Translation Pipeline

Retrieving and applying colors involves two coordinated functions. First, `nvm_get_colors` (lines 1056-1078 in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)) reads the palette from `NVM_COLORS`, defaulting to `bygre` if unset, and extracts the character at the requested index (1-5, or 6 for the system variant).

Next, `nvm_print_color_code` (lines 1092-1115) translates these single-character identifiers into ANSI escape sequences. The mapping follows this pattern:

- `r` → `0;31m` (red), `R` → `1;31m` (bright red)
- `g` → `0;32m` (green), `G` → `1;32m` (bright green)
- `b` → `0;34m` (blue), `B` → `1;34m` (bright blue)
- `c` → `0;36m` (cyan), `C` → `1;36m` (bright cyan)
- `y` → `0;33m` (yellow), `Y` → `1;33m` (bright yellow)
- `m` → `0;35m` (magenta), `M` → `1;35m` (bright magenta)
- `k` → `0;30m` (black), `K` → `1;30m` (bright black/dark gray)
- `e`/`E` → `0m` (empty/reset)
- `w` → `0;37m` (white), `W` → `1;37m` (bright white)

Invalid characters trigger an error message rather than rendering incorrectly.

### Applying Colors to Terminal Output

The final step occurs in `nvm_wrap_with_color_code` (lines 1080-1089 in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh)). This function receives an ANSI code and text fragment. If `nvm_has_colors` returns true, it wraps the text in `\033[<code>m<text>\033[0m`. Otherwise, it returns plain text. Throughout nvm's command implementations, higher-level helpers like `nvm_echo_with_colors` utilize this wrapping system to render status lines with the custom palette.

## Configuring Your Custom Color Scheme

You can customize nvm's appearance by setting `NVM_COLORS` before sourcing nvm.

### Using the Default Palette

If you do not set `NVM_COLORS`, nvm uses the default `bygre` palette:

```bash
nvm ls

```

This renders:
- **b**lue (`0;34m`): Installed versions
- **y**ellow (`0;33m`): LTS/system versions
- **g**reen (`0;32m`): Current version
- **r**ed (`0;31m`): Not-installed versions
- **e**mpty (`0m`): Default alias

### Setting a Custom Palette

Export your five-character code before loading nvm:

```bash

# Magenta-cyan-yellow-green-blue theme

export NVM_COLORS="McYgb"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

nvm ls  # Output now uses your custom colors

```

This configuration maps:
- `M` (bright magenta): Installed versions
- `c` (cyan): LTS/system versions
- `Y` (bright yellow): Current version
- `g` (green): Not-installed versions
- `b` (blue): Default alias

### Disabling Colors Entirely

To force plain text output regardless of terminal capabilities:

```bash
export NVM_NO_COLORS=--no-colors
nvm ls  # Uncolored text output

```

When `NVM_NO_COLORS` is set, `nvm_has_colors` returns false, causing `nvm_wrap_with_color_code` to skip ANSI wrapping.

## Technical Implementation Details in nvm.sh

The color system is entirely self-contained within the main [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) script:

- **Lines 81-86**: `nvm_has_colors` checks `tput colors`, TTY status, and `NVM_NO_COLORS`
- **Lines 1031-1052**: `nvm_set_colors` validates the five-character constraint and allowed character set `rRgGbBcCyYmMkKeW`
- **Lines 1049-1051**: Export of validated `NVM_COLORS` variable
- **Lines 1056-1078**: `nvm_get_colors` extracts specific palette indices with default fallback `bygre`
- **Lines 1080-1089**: `nvm_wrap_with_color_code` applies ANSI sequences conditionally
- **Lines 1092-1115**: `nvm_print_color_code` maps characters to ANSI codes (`0;31m`, `1;35m`, etc.)

The test suite in [`update_test_mocks.sh`](https://github.com/nvm-sh/nvm/blob/main/update_test_mocks.sh) (lines 29-32) validates this implementation by exercising custom palettes like `NVM_COLORS=0ygre` against `nvm ls-remote`.

## Summary

- nvm implements color customization through the `NVM_COLORS` environment variable, processed entirely within [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh).
- The `nvm_set_colors` function enforces a strict five-character format using only allowed identifiers from the set `rRgGbBcCyYmMkKeW`.
- The default palette `bygre` maps to blue, yellow, green, red, and empty/white for the five output categories.
- `nvm_get_colors` and `nvm_print_color_code` translate palette characters into ANSI escape sequences.
- Users can disable colors entirely by setting `NVM_NO_COLORS=--no-colors`.

## Frequently Asked Questions

### What is the default value for NVM_COLORS?

The default palette is `bygre`, which corresponds to **b**lue for installed versions, **y**ellow for LTS/system versions, **g**reen for the current version, **r**ed for not-installed versions, and **e**mpty/reset for the default alias. This default is defined in the `nvm_get_colors` function in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) as the fallback when `NVM_COLORS` is unset.

### Why does my NVM_COLORS setting show an error?

The `nvm_set_colors` function in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh) performs strict validation on the `NVM_COLORS` variable. It requires exactly five characters, and each character must be from the allowed set `rRgGbBcCyYmMkKeW`. If you provide fewer or more than five characters, or include characters outside this set (such as hex codes or RGB values), nvm outputs an error and refuses to apply the custom palette.

### How do I completely disable colored output in nvm?

Set the `NVM_NO_COLORS` environment variable to `--no-colors` before sourcing nvm. When this variable is present, the `nvm_has_colors` function returns false, which causes `nvm_wrap_with_color_code` to bypass ANSI escape sequence wrapping and output plain text regardless of terminal capabilities.

### Can I use RGB or hex color codes with NVM_COLORS?

No, nvm only supports the predefined single-character identifiers in the set `rRgGbBcCyYmMkKeW`. Each character maps to a specific ANSI 16-color escape sequence defined in the `nvm_print_color_code` function in [`nvm.sh`](https://github.com/nvm-sh/nvm/blob/main/nvm.sh). The system does not support 256-color palette codes or true-color (24-bit) RGB hex values.