Installation
Installing via package manager (npm, pip, cargo, maven)
Git2Docs CertifiedThis 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.
Before you begin, make sure your environment meets the following requirements:
- Node.js ≥ 22 — Chalk's
package.jsondeclares>=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
importsyntax. The simplest way to enable this is to add"type": "module"to yourpackage.json, or use the.mjsfile extension. - A package manager — npm, pnpm, or yarn. Examples below use npm; substitute your preferred tool.
Chalk requires Node.js ≥ 22 and an ESM-compatible runtime or bundler.
-
Install the package using your preferred package manager:
# npm npm install chalk# pnpm pnpm add chalk# yarn yarn add chalk -
Verify your project is set to ESM. Because Chalk is ESM-only, your project must either use
"type": "module"inpackage.json, or import Chalk from a.mjsfile:{ "type": "module" } -
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')throwsERR_REQUIRE_ESM. Use a dynamicimport()or upgrade to 22.12+.
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.
| Value | Description |
|---|---|
0 | All colors disabled |
1 | Basic color support (16 colors) |
2 | 256-color support |
3 | Truecolor 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 / Flag | Effect |
|---|---|
FORCE_COLOR=0 | Disable color (level 0) |
FORCE_COLOR=1 | Force level 1 (16 colors) |
FORCE_COLOR=2 | Force level 2 (256 colors) |
FORCE_COLOR=3 | Force level 3 (Truecolor) |
FORCE_COLOR=true or FORCE_COLOR= | Enable color (at least level 1); the exact level is still detected |
--no-color CLI flag | Sets level 0 — but overridden if FORCE_COLOR is set to a non-zero value |
--color CLI flag | Enables 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 flag | Enables level 2; takes precedence over a non-zero numeric FORCE_COLOR |
--color=16m CLI flag | Enables level 3; takes precedence over a non-zero numeric FORCE_COLOR |
COLORTERM=truecolor | Level 3 when the stream is a TTY (or color is forced); ignored for piped, non-TTY output |
TERM=dumb | Disables 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.
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. Usechalk.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.
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!'));
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=0or--no-coloris 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.