Node.js

mise installs Node.js from the official nodejs.org builds and selects a version per project. It can also read .nvmrc, .node-version and package.json, so projects set up for other version managers keep working.

Quick start

Select Node.js for the current project and check it without depending on shell activation:

mise use node@26
mise exec -- node --version

mise use writes node = "26" to mise.toml. Use mise use -g node@26 for a personal default; a project's version overrides it inside that project. mise upgrade node updates within the configured request.

nodejs is an alias for node; see the FAQ. For project recipes, see the Node.js cookbook.

Choosing a version

Request	Selects
node@26	The newest 26.x release
[email protected]	That release
node@lts	The newest release of the current LTS line
node@lts/krypton	The newest release of a named LTS line (lts-krypton also works)
node@latest	The newest release

List the available versions with mise ls-remote node, or one release line with mise ls-remote node 26. See version requests for the full syntax.

Version files

mise does not read .nvmrc, .node-version or package.json until you enable them for Node.js:

mise settings add idiomatic_version_file_enable_tools node

This changes your global config. Add --local to enable it in the project's mise.toml instead, so teammates get the same behavior. See idiomatic version files.

.nvmrc aliases such as lts/* and lts/iron work as they do in nvm, and a leading v is ignored. To read .nvmrc and .node-version but not package.json:

mise settings add idiomatic_version_file_disable_files node:package.json

package.json

mise reads devEngines.runtime when its name is node:

package.json

{
  "devEngines": {
    "runtime": { "name": "node", "version": "26.10.0" }
  }
}

This selects Node.js 26.10.0. devEngines.runtime can be an object or an array; mise reads the first entry of an array. See the Bun and Deno pages for other runtimes.

mise does not read engines.node, which describes the Node.js versions a package is compatible with, not the version to develop with. If a project only has an engines range, select a version explicitly:

mise use node@24

Package managers

npm ships with Node.js. mise can also install and select npm, pnpm and Yarn as separate tools, without Corepack, and aube, which works with existing npm, pnpm and Yarn lockfiles. See the Node.js cookbook for project recipes with pnpm and aube.

Pin the npm version

To keep a team on the same npm, and avoid package-lock.json churn between npm versions, pin npm next to Node.js:

mise.toml

[tools]
node = "26"
npm = "11"

To write exact versions for both:

mise use --pin node@lts npm@latest

This writes the resolved versions to mise.toml. Inside the mise environment, the separately configured npm takes precedence over the npm bundled with Node.js; check it with mise exec -- npm --version. This selects the npm executable; the project's lockfile still controls its dependencies.

Package-manager versions in package.json

mise can read the npm, pnpm or Yarn version from package.json. Enable each package manager that a repository may declare:

mise.toml

[settings]
idiomatic_version_file_enable_tools = ["npm", "pnpm", "yarn"]

mise reads a matching devEngines.packageManager declaration first, then the top-level packageManager field. The declaration's name must match the enabled tool:

package.json

{
  "packageManager": "[email protected]"
}

This selects pnpm 10.15.0. The equivalent devEngines declaration is:

package.json

{
  "devEngines": {
    "packageManager": { "name": "pnpm", "version": "10.15.0" }
  }
}

devEngines.packageManager can also be an array; mise reads its first entry. For Bun's runtime and package-manager precedence, see Bun version files.

A Corepack-style checksum suffix (+sha1, +sha224, +sha256, +sha384 or +sha512) is verified against the exact package-manager artifact before installation:

package.json

{
  "packageManager": "[email protected]+sha224.88208eb7c2e7de6ed534fa298248dee656723116995eda4b508fd0c9"
}

For npm, pnpm and Yarn 1, that artifact is the npm registry tarball. For Yarn 2 and later it is Yarn's published CLI file, and the declaration must name an exact Yarn version. Without a checksum, mise installs the package manager through its usual registry backend and that backend's verification.

The suffix must be <algorithm>.<hex digest> with one of the algorithms above; mise ignores a declaration with any other suffix. When devEngines.packageManager names the same version as packageManager without a suffix of its own, the checksum from packageManager still applies.

Unlike Corepack, mise does not pick a known-good package-manager version when a project declares none. Set the version in mise.toml, package.json or your global config.

Corepack

mise installs package managers itself, so Corepack is not needed. If you still want Corepack's shims, set node.corepack to true; mise then runs corepack enable after installing any Node.js version that includes Corepack.

Global npm packages

npm install -g installs into the active Node.js version, unless your .npmrc sets a different prefix. A globally installed command is therefore not available after you switch Node.js versions.

On macOS and Linux, mise replaces each version's bin/npm with a small wrapper that runs mise reshim after global installs and uninstalls, so new commands get shims. Turn it off with node.npm_shim.

To keep a CLI across Node.js versions, install it as its own tool with the npm backend, for example mise use -g npm:typescript.

How mise installs Node.js

mise downloads the official binary archive for your platform from node.mirror_url (https://nodejs.org/dist/ by default), checks it against the release's SHASUMS256.txt, and verifies the OpenPGP signature on that file (node.gpg_verify). A missing signature fails the install, except for musl builds from unofficial-builds, which publishes none. It then runs node -v and npm -v. mise sets no Node.js-specific environment variables; the version's bin directory goes on PATH.

mise lock takes its checksums from the same SHASUMS256.txt and verifies the same signature before it records them.

When no binary exists for your platform, mise compiles Node.js from source, unless node.compile is false. If mise.lock pins a checksum for the binary and the download answers 404, the install fails instead; run mise lock node to lock another artifact.

On Alpine and NixOS, mise currently compiles from source by default, because all_compile defaults to true there. This default is deprecated, and mise 2027.8.0 switches to precompiled binaries. To use precompiled binaries now, set node.compile = false or all_compile = false; on NixOS, enable nix-ld first. To keep compiling, set all_compile = true explicitly.

An installed plugin named node takes precedence over the built-in installer. If mise behaves differently from this page, check mise plugins ls and see selecting another implementation.

Compiling from source

Set node.compile to build Node.js instead of downloading a binary. Install Node.js's build dependencies first:

mise settings node.compile=true
mise install node@26

mise uses ninja when it is on PATH. The node.ninja, node.concurrency, node.configure_opts, node.cflags and node.apply_patches settings tune the build.

Unofficial builds

The unofficial builds project publishes Node.js for platforms the official builds do not cover.

On musl hosts such as Alpine, mise detects musl and, when it downloads a binary rather than compiling (see the Alpine note above), fetches Node.js's musl flavor from the unofficial builds automatically while node.mirror_url is the default. The libc setting set to musl has the same effect.

For other platforms, such as linux-loong64 or linux-armv6l, or for the glibc-217 flavor built against an older glibc, point mise at the unofficial builds:

mise settings node.mirror_url=https://unofficial-builds.nodejs.org/download/release/

Then choose a flavor with node.flavor if you need one:

mise settings node.flavor=glibc-217

Migrating from nvm, nodenv, or Homebrew

To reuse Node.js versions you already installed, link them into mise with mise sync node:

mise sync node --nvm     # reads versions under node.nvm_dir (NVM_DIR)
mise sync node --nodenv  # reads versions under node.nodenv_root (NODENV_ROOT)
mise sync node --brew    # reads Homebrew's versioned node@NN formulae

mise sync does not overwrite versions mise installed itself. Then enable .nvmrc and .node-version as described in Version files.

Tool options

Node.js has no Node.js-specific options. install_env reaches source builds, the node -v and npm -v checks, default package installs, corepack enable and postinstall commands. For example, to override compiler flags for a source build:

mise.toml

[tools]
node = { version = "26", install_env = { CFLAGS = "-O2" } }

Other generic options are described in tool options.

Default packages file deprecated

mise installs the packages listed in ~/.default-npm-packages (node.default_packages_file), one per line, with npm install --global into each new Node.js version. mise warns about this file from 2026.11.0 and stops reading it in 2027.11.0. Install npm CLIs with the npm backend instead, for example "npm:typescript" = "latest", or use a postinstall command for packages every Node.js version needs.

Settings

Set these under [settings] in a config file, with mise settings set, or with a setting's environment variable where it has one. See which value wins when a setting is set in more than one place.

node.apply_patches

Patch files or URLs to apply to the Node.js source before building it.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_APPLY_PATCHES

List one patch file or URL per line. mise applies them to the extracted source before ./configure runs. They apply only to source builds: with node.compile = true, or when no precompiled build exists for the version and mise compiles instead. When mise installs a precompiled build, it warns that the patches were skipped.

node.cflags

Extra CFLAGS for compiling Node.js, for example to replace -O3.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_CFLAGS

When unset, mise uses NODE_CFLAGS from the environment.

node.compile

Compile Node.js from source instead of using a precompiled build.

• Type: boolean
• Default: unset
• Environment variable: MISE_NODE_COMPILE

false uses only precompiled builds and fails when none exists. When unset, all_compile decides; if that is unset too, mise uses a precompiled build when one exists and compiles otherwise. See Building from source.

node.concurrency

Number of parallel jobs (make -j) when compiling Node.js.

• Type: integer
• Default: physical CPU cores, or unset when node.ninja is on
• Environment variable: MISE_NODE_CONCURRENCY

Values below 1 count as 1. With node.ninja, ninja picks the job count when this is unset.

node.configure_opts

Extra arguments for ./configure when compiling Node.js.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_CONFIGURE_OPTS

When unset, mise uses NODE_CONFIGURE_OPTS from the environment.

node.corepack

Run corepack enable after installing a Node.js version, so yarn and pnpm go through Corepack.

• Type: boolean
• Default: false
• Environment variable: MISE_NODE_COREPACK

Applies to Node.js versions that include Corepack. When node.npm_shim is off, mise also runs corepack enable npm. mise installs package managers itself, so Corepack is optional; see Corepack.

node.default_packages_filedeprecated

File listing npm packages to install globally into each new Node.js version.

• Type: path
• Default: "~/.default-npm-packages"
• Environment variable: MISE_NODE_DEFAULT_PACKAGES_FILE
• Deprecated: Default npm package files are deprecated. Use tool-level postinstall hooks for packages that should be installed into every node version, or use the npm: backend for CLI tools.

One package per line, with an optional version:

typescript@latest
@types/node@^24

When this is unset, mise uses NODE_DEFAULT_PACKAGES_FILE, then ~/.default-nodejs-packages or ~/.default-node-packages if one exists, and otherwise ~/.default-npm-packages. See Default packages file.

node.flavor

Linux build flavor of Node.js to download, such as musl or glibc-217.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_FLAVOR

Flavors come from the unofficial builds project, so also set node.mirror_url to https://unofficial-builds.nodejs.org/download/release/. musl is the exception: with the default mirror, mise downloads it from the unofficial builds by itself, and it selects musl automatically on musl hosts. See Unofficial builds.

node.gpg_verify

Check the OpenPGP signature of the SHASUMS256.txt file that node.verify checks downloads against.

• Type: boolean
• Default: true
• Environment variable: MISE_NODE_GPG_VERIFY

mise checks the signature itself, so gpg does not need to be installed. It runs only when node.verify is on, for installs and for the checksums mise lock records. A missing .sig fails the check, except on unofficial-builds, which signs nothing. Set to false to skip the check, for example for a mirror that does not copy the signatures or for one of the few early releases (such as 4.0.0 and 5.12.0) that never published one. The global gpg_verify setting sets the default.

node.make

Command to run instead of make when compiling Node.js, such as gmake.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_MAKE

Used for both the build and make install.

node.make_install_opts

Extra arguments for make install when compiling Node.js.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_MAKE_INSTALL_OPTS

When unset, mise uses NODE_MAKE_INSTALL_OPTS from the environment.

node.make_opts

Extra arguments for make when compiling Node.js.

• Type: string
• Default: unset
• Environment variable: MISE_NODE_MAKE_OPTS

When unset, mise uses NODE_MAKE_OPTS from the environment.

node.mirror_url

Base URL that mise downloads Node.js archives and their SHASUMS256.txt checksums from.

• Type: URL
• Default: "https://nodejs.org/dist/"
• Environment variable: MISE_NODE_MIRROR_URL

When unset, mise uses NODE_BUILD_MIRROR_URL from the environment, then the default. With the default URL, musl builds come from the unofficial builds site instead. See Unofficial builds.

node.ninja

Build Node.js with ninja instead of make when compiling from source.

• Type: boolean
• Default: true when ninja is on PATH
• Environment variable: MISE_NODE_NINJA

With ninja, and node.concurrency unset, ninja chooses how many jobs to run in parallel.

node.nodenv_root

Root directory of nodenv, which mise sync node --nodenv imports Node.js versions from.

• Type: path
• Default: "~/.nodenv"
• Environment variable: NODENV_ROOT

node.npm_shim

Wrap each Node.js version's npm so that npm install -g runs mise reshim afterwards.

• Type: boolean
• Default: true
• Environment variable: MISE_NODE_NPM_SHIM

The wrapper reshims after global installs and uninstalls, so new global commands get shims. It is not installed on Windows. Turn it off to let Corepack or a global npm install -g npm@... manage bin/npm directly. See Global npm packages.

node.nvm_dir

Directory of nvm, which mise sync node --nvm imports Node.js versions from.

• Type: path
• Default: "~/.nvm"
• Environment variable: NVM_DIR

node.verify

Verify downloaded Node.js archives against the SHA-256 checksums in SHASUMS256.txt.

• Type: boolean
• Default: true
• Environment variable: MISE_NODE_VERIFY

When the lockfile has no checksum for an archive, mise downloads SHASUMS256.txt, checks its OpenPGP signature as node.gpg_verify allows, and records the archive's checksum. Setting this to false skips both the checksum file and its signature check. A checksum already in the lockfile is still verified.