Getting started

Install mise, then give a project its own Node.js version, an environment variable and a task. Steps 1 to 3 work without changing your shell configuration; step 4 adds optional shell activation.

Joining a project that already has a mise.toml? Install mise (step 1), read the project's mise.toml (see trust), then run mise install in the project directory and mise tasks ls to list its tasks. Use mise in an existing project covers adding mise to a project that does not use it yet.

1. Install mise

On macOS or Linux, run the installer:

curl -fsSL https://mise.run | sh
~/.local/bin/mise --version
# 2026.x.x linux-x64 (2026-xx-xx)

The installer puts the mise executable at ~/.local/bin/mise. If your shell cannot find mise in the next steps, run it as ~/.local/bin/mise until you activate mise in step 4, which adds it to PATH.

On Windows, run winget install jdx.mise. For Homebrew, apt, dnf and other package managers, see Installing mise.

2. Run a tool

mise exec runs a command with a specific tool version:

mise exec node@24 -- node --version
# v24.x.x

mise downloads Node.js 24 if it is not installed, then runs the command after --. This does not change any config file or your current shell's environment.

3. Set up a project

Create a directory and select Node.js 24 for it:

mkdir my-project
cd my-project
mise use node@24

mise use installs Node.js 24 if needed and records the request in a new mise.toml:

mise.toml

[tools]
node = "24"

Set an environment variable

Run mise set to add an [env] section:

mise set NODE_ENV=development

mise.toml now contains:

mise.toml

[tools]
node = "24"

[env]
NODE_ENV = "development"

Commands run through mise get both the tool and the variable:

mise exec -- node -p process.env.NODE_ENV
# development

You can also load variables from a .env file.

Run a task

Add a task to the same mise.toml:

mise.toml

[tasks.hello]
description = "Print the Node.js version and NODE_ENV"
run = 'node -e "console.log(process.version, process.env.NODE_ENV)"'

mise run hello

[hello] $ node -e "console.log(process.version, process.env.NODE_ENV)"
v24.x.x development

mise run installs missing tools, sets the project's environment, then runs the task.

Check what mise selected

From the project directory:

mise config ls     # config files in use
mise ls --current  # selected tool versions
mise tasks ls      # available tasks

Trust project configuration

A mise.toml with [env], hooks, templates or settings can run code or change your environment, so mise loads it only once it is trusted: files you write with mise use or mise set are trusted, and so is a project where you run mise install, mise exec or mise run. For a project from someone else, read its config, tasks included, before running those commands or mise trust; see Configuration trust for the rules.

Share the project

Commit mise.toml. Teammates and CI run mise install in the project to get the same tools. "24" is a prefix, not an exact version, so two machines can resolve it to different Node.js 24 releases; to record exact versions, add a lockfile with mise lock.

4. Activate mise optional

Activate mise in your interactive shell so that entering a project directory puts its tools on PATH and sets its environment variables. Activation adds a hook that runs at each prompt and directory change and updates the environment for the current directory. Scripts and CI do not need activation; keep using mise exec and mise run there.

Run the command for your shell once. It appends the activation line to your shell's startup file:

bash

echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc

zsh

echo 'eval "$(~/.local/bin/mise activate zsh)"' >> "${ZDOTDIR:-$HOME}/.zshrc"

fish

mkdir -p ~/.config/fish
echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish

PowerShell

if (-not (Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force | Out-Null }
Add-Content $PROFILE '(&mise activate pwsh) | Out-String | Invoke-Expression'

If a package manager installed mise, write mise in place of ~/.local/bin/mise. With Homebrew, fish activates mise without this step. Shell setup covers Nushell, Xonsh, Elvish, Git Bash and cmd.exe, and has versions of these lines that do not add a duplicate when run twice.

Open a new terminal, then compare a directory inside the project with one outside it:

cd my-project
node --version
# v24.x.x
cd ..
node --version
# another Node.js version, or "command not found"

To use a version outside any project, set a personal default with mise use --global node@24. It writes ~/.config/mise/config.toml, and project configuration overrides it.

Run mise doctor to check the setup. Editors and other programs that do not read your shell's startup files can use shims instead, which have some limits.

5. Find more tools

Use the registry to find tool names such as node, python, jq and ripgrep. Usually the name is all you need. Run these from the my-project directory; after the step 4 demo, cd my-project first:

mise use ripgrep
mise exec -- rg --version

This adds ripgrep to the project's mise.toml. Outside a project, mise use creates a mise.toml in the current directory, or writes the global config when that directory is your home directory.

A backend tells mise where to get a tool and how to install it. You can name one explicitly, including for tools without a registry entry:

mise exec github:BurntSushi/ripgrep -- rg --version

Some backends need another tool or package manager, such as Node.js for npm:. Check the backend guide before using a new ecosystem.

If something does not work

Run mise doctor to check your setup. If a tool works through mise exec but not as a plain command, check shell activation and open a new terminal. See Troubleshooting for other problems.

GitHub API rate limits

If an error reports a GitHub API rate limit, give mise a GitHub token.

Next steps

• Use mise in an existing project
• Tasks: build, test and other project commands
• Editors and continuous integration
• Shell completions
• Bootstrap: system packages, dotfiles and services for a whole machine