Amazing CLIfor Terminal
Guide

Installation

Installing via package manager (npm, pip, cargo, maven)

Git2Docs Certified

Overview

This page walks you through installing Chalk and importing it into your Node.js project or browser bundle. Chalk is an ESM-only library — it ships a single ES module entry point with no runtime dependencies, so your dependency graph stays clean. After installation you will have access to the default chalk instance and the Chalk constructor for creating isolated instances with custom color levels.


Prerequisites

Before you begin, make sure your environment meets the following requirements:

  • Node.js ≥ 22 — Chalk's package.json declares >=22. CI is verified against Node 22 and Node 26; other versions are not tested.
  • ESM-compatible project — Chalk ships no CommonJS build. Your project must be able to use ES module import syntax. The simplest way to enable this is to add "type": "module" to your package.json, or use the .mjs file extension.
  • A package manager — npm, pnpm, or yarn. Examples below use npm; substitute your preferred tool.

Installation

Chalk requires Node.js ≥ 22 and an ESM-compatible runtime or bundler.

  1. Install the package using your preferred package manager:

    # npm
    npm install chalk
    
    # pnpm
    pnpm add chalk
    
    # yarn
    yarn add chalk
    
  2. Verify your project is set to ESM. Because Chalk is ESM-only, your project must either use "type": "module" in package.json, or import Chalk from a .mjs file:

    {
      "type": "module"
    }
    
  3. Import Chalk in your source file:

    import chalk from 'chalk';
    

    That's all — Chalk automatically detects your terminal's color capability (none, 16-color, 256-color, or Truecolor) at import time.

Node.js ≥ 22.12 and CommonJS: On Node.js ≥ 22.12, require('chalk') succeeds and returns the ES module namespace. Access the default export via .default:

// Node.js ≥22.12 only
const chalk = require('chalk').default;

On Node.js 22.0–22.11, require('chalk') throws ERR_REQUIRE_ESM. Use a dynamic import() or upgrade to 22.12+.


Configuration

Chalk gives you two ways to control color output: the level property on any Chalk instance, and environment variables / CLI flags that are read at import time.

chalk.level

The level property controls how much color Chalk emits. It is detected automatically but can be overridden.

ValueDescription
0All colors disabled
1Basic color support (16 colors)
2256-color support
3Truecolor support (16 million colors)

Setting level on the global chalk instance affects all code that imports it, which makes it unsuitable for reusable modules. Create an isolated instance instead:

import { Chalk } from 'chalk';

const customChalk = new Chalk({ level: 0 }); // colors disabled

Passing any value that is not a safe integer from 0 to 3 — either to the constructor option or by assigning to the level property — throws an Error with the message The \level` should be an integer from 0 to 3`.

import { Chalk } from 'chalk';

const c = new Chalk({ level: 5 }); // throws Error

Omit the level option (or pass undefined) to let Chalk detect the level from the environment.


Environment variables

These are read by the vendored #supports-color module at import time and determine the auto-detected level.

Variable / FlagEffect
FORCE_COLOR=0Disable color (level 0)
FORCE_COLOR=1Force level 1 (16 colors)
FORCE_COLOR=2Force level 2 (256 colors)
FORCE_COLOR=3Force level 3 (Truecolor)
FORCE_COLOR=true or FORCE_COLOR=Enable color (at least level 1); the exact level is still detected
--no-color CLI flagSets level 0 — but overridden if FORCE_COLOR is set to a non-zero value
--color CLI flagEnables color at at least level 1, even on non-TTY streams; the level is still detected and can be higher (e.g. 2 with TERM=xterm-256color)
--color=256 CLI flagEnables level 2; takes precedence over a non-zero numeric FORCE_COLOR
--color=16m CLI flagEnables level 3; takes precedence over a non-zero numeric FORCE_COLOR
COLORTERM=truecolorLevel 3 when the stream is a TTY (or color is forced); ignored for piped, non-TTY output
TERM=dumbDisables color unless FORCE_COLOR overrides

Note that FORCE_COLOR takes precedence over --no-color. Chalk does not read NO_COLOR.

Numeric FORCE_COLOR values are capped at 3.


supportsColor and supportsColorStderr

Chalk exports the detected color support objects for stdout and stderr:

import { supportsColor, supportsColorStderr } from 'chalk';

if (supportsColor) {
  console.log(`stdout color level: ${supportsColor.level}`);
}

if (supportsColorStderr) {
  console.log(`stderr color level: ${supportsColorStderr.level}`);
}

Each export is either a ColorSupport object with a level property, or false when color is not detected. Always guard with a truthy check before accessing .level.


Usage

Once installed and imported, you style strings by chaining style properties and color methods on the chalk default export, then calling the final builder as a function with your string arguments.

Basic styling

import chalk from 'chalk';

console.log(chalk.blue('Hello world!'));

Chaining styles

Chain as many modifiers and colors as you need. Each property access returns a new cached builder; the last conflicting style in a chain wins visually.

import chalk from 'chalk';

console.log(chalk.blue.bgRed.bold('Hello world!'));

Multiple string arguments

Pass multiple arguments to a chalk builder; they are joined with a single space:

import chalk from 'chalk';

console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));

Nesting styles

Nest chalk calls inside each other to apply inner styles that reset cleanly:

import chalk from 'chalk';

console.log(chalk.red('Hello', chalk.underline.bgBlue('world') + '!'));

Defining reusable themes

Capture a partially-applied builder in a variable to create a named style:

import chalk from 'chalk';

const error = chalk.bold.red;
const warning = chalk.hex('#FFA500');

console.log(error('Error!'));
console.log(warning('Warning!'));

Isolated instances

Use the Chalk constructor when you need a color level that differs from the global default — for example, when writing to a file stream where ANSI codes are unwanted, or in a library that must not affect consumers' chalk settings:

import { Chalk } from 'chalk';

const plainChalk = new Chalk({ level: 0 }); // no ANSI codes
const truecolorChalk = new Chalk({ level: 3 }); // always Truecolor

Embedding styles in template literals

Call chalk inside a regular template literal's ${} expressions:

import chalk from 'chalk';

console.log(`
CPU: ${chalk.red('90%')}
RAM: ${chalk.green('40%')}
DISK: ${chalk.yellow('70%')}
`);

console.log string substitution

Standard %s substitution works alongside chalk:

import chalk from 'chalk';

const name = 'Sindre';
console.log(chalk.green('Hello %s'), name);

Important: Do not use chalk as a tagged template literal (chalk.red\text ${val}`). Core chalk does not support tagged template syntax — the values will not be interpolated correctly. Use chalk.red(text ${val}) instead, or install the separate [chalk-template`](https://github.com/chalk/chalk-template) package for tagged template support.

Browser bundles

In browser environments, Chalk automatically uses a Chromium-based color detector. It is selected by the default condition of the #supports-color entry in Chalk's package.json "imports" field (there is no "browser" condition), so any bundler that resolves package imports for non-Node targets picks it up. Chromium brand version > 93 receives level 3; any other Chrome/Chromium user agent receives level 1; non-Chromium browsers or missing navigator receive level 0. No special configuration is needed — import Chalk the same way as in Node.js.


Examples

Apply a single color

import chalk from 'chalk';

console.log(chalk.blue('Hello world!'));

Combine styled and unstyled text

import chalk from 'chalk';

console.log(chalk.blue('Hello') + ' World' + chalk.red('!'));

Chain multiple styles

import chalk from 'chalk';

console.log(chalk.blue.bgRed.bold('Hello world!'));

Pass multiple arguments (joined with spaces)

import chalk from 'chalk';

console.log(chalk.blue('Hello', 'World!', 'Foo', 'bar', 'biz', 'baz'));

Nest styles

import chalk from 'chalk';

console.log(
  chalk.green(
    'I am a green line ' +
    chalk.blue.underline.bold('with a blue substring') +
    ' that becomes green again!'
  )
);

Use Truecolor: hex and rgb

import chalk from 'chalk';

console.log(chalk.hex('#DEADED').bold('Bold gray!'));
console.log(chalk.rgb(123, 45, 67).underline('Underlined reddish color'));

Background and underline color variants

import chalk from 'chalk';

console.log(chalk.bgHex('#DEADED').underline('Hello, world!'));
console.log(chalk.bgRgb(15, 100, 204).inverse('Hello!'));
console.log(chalk.underlineHex('#DEADED').underlineCurly('Hello, world!'));

Define reusable theme variables

import chalk from 'chalk';

const error = chalk.bold.red;
const warning = chalk.hex('#FFA500'); // Orange

console.log(error('Error!'));
console.log(warning('Warning!'));

Create an isolated instance with a fixed color level

import { Chalk } from 'chalk';

const customChalk = new Chalk({ level: 0 });

console.log(customChalk.red('This text has no color codes'));

Use %s substitution with chalk

import chalk from 'chalk';

const name = 'Sindre';
console.log(chalk.green('Hello %s'), name);
// => 'Hello Sindre'

Inspect detected color support

import { supportsColor, supportsColorStderr } from 'chalk';

if (supportsColor) {
  console.log(`Stdout supports color at level ${supportsColor.level}`);
} else {
  console.log('Stdout does not support color');
}

Validate available style names

import { modifierNames, foregroundColorNames } from 'chalk';

console.log(modifierNames.includes('bold'));
// => true

console.log(foregroundColorNames.includes('pink'));
// => false

CommonJS interop on Node.js ≥ 22.12

// Works only on Node.js >=22.12
const chalk = require('chalk').default;

console.log(chalk.green('Hello from CJS!'));

Troubleshooting

ERR_REQUIRE_ESM when calling require('chalk')

Symptom: Your CommonJS file throws Error [ERR_REQUIRE_ESM]: require() of ES Module … not supported.

Cause: You are running Node.js 22.0–22.11. On those versions, the Node.js CJS loader cannot load ES modules synchronously.

Fix: Upgrade to Node.js ≥ 22.12, where require() of an ES module is permitted and returns the module namespace. Then access the default export via .default:

const chalk = require('chalk').default;

Alternatively, convert your file to ESM (import syntax) or use a dynamic import():

const { default: chalk } = await import('chalk');

No colors appear in the terminal

Symptom: Chalk calls complete without error but output is plain text with no color.

Cause: chalk.level is 0, which disables all ANSI codes. This can happen when:

  • The terminal or CI environment does not advertise color support.
  • FORCE_COLOR=0 or --no-color is set in the environment.
  • A new Chalk({ level: 0 }) instance was used.

Fix: Check the detected level and override if necessary:

import chalk from 'chalk';

console.log(chalk.level); // 0 means color is disabled

Force color on by setting the environment variable before running your script:

FORCE_COLOR=1 node your-script.js

Or create an instance with an explicit level:

import { Chalk } from 'chalk';
const chalk = new Chalk({ level: 3 });

Error: The \level` should be an integer from 0 to 3`

Symptom: Constructing a Chalk instance or assigning to chalk.level throws this error.

Cause: The value passed is not a safe integer in the range 0–3 (e.g., 4, 1.5, 'auto', or null).

Fix: Use only 0, 1, 2, or 3. To restore auto-detection, omit the option or pass undefined:

import { Chalk } from 'chalk';

const c = new Chalk({ level: 2 }); // valid
const auto = new Chalk();           // auto-detected

Tagged template literals produce garbled or misplaced output

Symptom: chalk.red\Hello ${name}`prints something likeHello , Sindre` — the interpolated value appears after a space rather than inline.

Cause: Core Chalk does not support tagged template literals. When used as a tag, the raw string array is coerced and joined, while interpolated values are appended separately.

Fix: Use a standard function call with a template literal expression:

import chalk from 'chalk';

const name = 'Sindre';
console.log(chalk.red(`Hello ${name}`)); // correct

If you need tagged template literal syntax with proper interpolation, install chalk-template.


FORCE_COLOR does not disable color when --no-color is also set

Symptom: You run your script with --no-color but color still appears.

Cause: FORCE_COLOR takes precedence over --no-color. If FORCE_COLOR is set to any non-zero value in the environment, the --no-color flag is overridden.

Fix: Unset FORCE_COLOR from the environment, or explicitly set FORCE_COLOR=0 to ensure color is disabled regardless of other flags.


Project uses CommonJS and Node.js < 22 — cannot upgrade

Symptom: You cannot use ESM and cannot upgrade to Node.js ≥ 22.12.

Cause: Chalk has been ESM-only since version 5, and Chalk 6 requires Node.js ≥ 22. (Chalk 5 supported Node.js 12.17+, 14.13+ and 16+, but is also ESM-only.)

Fix: Use Chalk 4, which supports CommonJS and older Node.js versions. See the Chalk v5 release notes for migration guidance.