A brief introduction to mise

mise is a tool version manager and a task runner. It replaces tools like asdf, nvm, pyenv, sdkman, rbenv, …

In this post, I will show you how to migrate from nvm (node-version manager) to mise. Let’s first start with a quick tour of mise.

Here is how you can install mise if you are using zsh with ohmyzsh. (if you are using another shell, go through the getting-started guide

curl https://mise.run | sh
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
source ~/.zshrc

mise use -g usage

mkdir -p ~/.oh-my-zsh/custom/completions
mise completion zsh > ~/.oh-my-zsh/custom/completions/_mise

source ~/.zshrc

You have now installed mise. Let’s use it to manage node. It’s very similar to nvm.

# Install `nodeJS` lts globally
mise use -g node@lts
node -v
# v22.x.x

# mise does not require shims, the real path is used
which node
# ~/.local/share/mise/installs/node/22.x.x/bin/node

# we can also install `npm` packages globally and let mise manage them
mise use -g npm:mocha

# the list of globally installed tools is stored in ~/.config/mise/config.toml
cat ~/.config/mise/config.toml
# [tools]
# node = "lts"
# "npm:mocha" = "latest"

# in this project we will use node 23
mkdir my-project && cd my-project
mise use node@23
node -v
# v23.x.x

# if we leave the current directory, we are back on node 22
cd ..
node -v 
# v22.x.x

# mise also supports .nvmrc files
mkdir nvm-project && cd nvm-project
echo "18" > .nvmrc
mise install
node -v
# v18.x.x

In addition to this, mise supports tasks

Why migrate from nvm?

NVM (node version manager) is a popular way to install NodeJS. There are others like fnm or volta.¹

• While nvm only manages Node.js versions, mise can handle multiple languages and tools like python, go, ruby, deno, bun, … It can also help you to manage binaries from npm
• mise supports tasks as well as environment variables
• mise is written in rust and is faster than nvm. It won’t slow down your shell.
• mise supports .nvmrc and .node-version making it easy to switch

Migrating from nvm to mise

As indicated above, mise can read .nvmrc files to determine the required Node.js version. This will help to migrate from nvm.

Example setup

For the migration example, we will consider the following NodeJS setup:

• Node.js 20 and 22 are installed globally using nvm
• Node 22 is used by default
• There are two projects, one using Node 17 and the other using Node 18

The project directories contain .nvmrc files:

- node-project-17/.nvmrc: 17
- node-project-18/.nvmrc: 18

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

nvm install 22
nvm install 20
nvm alias default 22

mkdir -p node-18-project && cd node-18-project && echo "18" > .nvmrc && nvm install && cd -
mkdir -p node-17-project && cd node-17-project && echo "17" > .nvmrc && nvm install && cd -

Stop loading nvm

If it’s not already done, install mise (see Getting Started).

Open your shell configuration file (.bashrc, .zshrc, …) and remove or comment out the nvm initialization script:

# Comment out or remove these lines
# export NVM_DIR="$HOME/.nvm"...

then, restart your shell.

Migration Options

You now have two options for migration:

Option A: Clean Installation (Remove nvm)

Unload nvm and remove its directory:

nvm_dir="${NVM_DIR:-~/.nvm}"
nvm unload
rm -rf "$nvm_dir"

Reinstall your global Node.js version with mise:

mise use -g node@22

This will install Node.js 22 globally and set it as the default version. If you also want to install Node.js 20, you can run mise install node@20 without setting it as the default version.

Install Node.js 17 and 18 for the projects:

cd node-project-17
mise install

cd ../node-project-18
mise install

Option B: Keep Existing nvm Installations (Symlink)

This option is useful if you want to keep your existing nvm installations and use them with mise. (You won’t need to reinstall global packages for example.)

Sync existing nvm installations with mise:

mise sync node --nvm

Verify the sync by listing installations with mise ls:

Tool  Version            Config Source Requested
node  17.9.1 (symlink)
node  18.20.4 (symlink)
node  20.11.0 (symlink)
node  22.1.0 (symlink)

If you navigate to node-project-17 and node-project-18, you will see that the correct Node.js version is used.

node-18-project# mise ls
Tool  Version            Config Source           Requested
node  17.9.1 (symlink)
node  18.20.4 (symlink)  /node-18-project/.nvmrc 18
node  22.11.0 (symlink)
node  23.1.0 (symlink)
node-18-project# node -v
v18.20.4

Let’s now create a new project with Node 19:

mkdir node-project-19 && cd node-project-19
mise use node@19 # create a mise.toml file with node@19

Tool  Version            Config Source               Requested
node  17.9.1 (symlink)
node  18.20.4 (symlink)
node  19.9.0             /node-project-19/.mise.toml 19
node  22.11.0 (symlink)
node  23.1.0 (symlink)