Skip to content
Get packs

Guide · Open source

How to use mise: install, set tool versions and run tasks

Updated · written with AI from the project's own documentation and checked against our catalogue data

mise (short for mise-en-place) is a command-line tool that manages the software a project needs, such as Node.js, Python or Rust versions, with a separate version per project. It also loads environment variables and runs project tasks from one mise.toml file. This guide walks through installing it, running a tool, configuring a project and running a task so you can use it in your own work.

misejdx/mise · ★ 35.7k · MIT

Quick start

  1. 1Install mise. Run the macOS or Linux install command, or use winget install jdx.mise on Windows. Check the version with mise --version or ~/.local/bin/mise --version.
  2. 2Test a tool with mise exec. Run mise exec node@24 -- node --version to use a version without changing your shell.
  3. 3Create a project config. In a project folder, run mise use node@24 and mise set to write mise.toml.
  4. 4Add a task. Use mise tasks add to define a task, then run it with mise run <task>.
  5. 5Commit mise.toml. Commit the file so teammates and CI run mise install or mise run with the same setup.
  6. 6Activate in your shell (optional). Add the activate line for bash, zsh or fish to your shell config and open a new terminal.

Install mise on macOS, Linux or Windows

On macOS or Linux, run the install command from the README, then check the version using the path the installer uses.

On Windows, install it with winget. The README points to Homebrew, apt, dnf, Scoop and other package managers on the Installing mise page.

  • The installer places the binary at ~/.local/bin/mise.
  • If ~/.local/bin is not on your PATH yet, run ~/.local/bin/mise in place of mise until you activate it.
curl -fsSL https://mise.run | sh ~/.local/bin/mise --version

Run a tool without changing your shell

The mise exec command downloads the requested version if needed and runs the command after -- with that version on PATH. Your shell and config files stay untouched, which makes it a safe first test.

mise exec node@24 -- node --version

Configure a project with mise.toml

Create a project directory, select a Node.js version, set an environment variable and add a task. These commands write a mise.toml file in the project.

Commit mise.toml so teammates and CI get the same setup when they run mise install or mise run. Run mise lock to record exact versions and checksums in a lockfile.

  • mise use --global node@24 sets a personal default in ~/.config/mise/config.toml.
  • "24" requests the latest release in the Node.js 24 series.
mkdir my-project && cd my-project mise use node@24 mise set NODE_ENV=development mise tasks add hello -- node -e "console.log(process.version, process.env.NODE_ENV)"

Run a project task

The mise run command runs a task defined in your config with its tools and environment already set up. Tasks can also depend on other tasks, as the README's example shows with a test task that depends on build.

  • Tasks can be defined in mise.toml or as scripts in mise-tasks/.
  • Tasks support dependencies, parallel execution and file watching, according to the README.
mise run hello

Turn on shell activation (optional)

Shell activation updates PATH and project environment variables when you change directories, so you can call node directly without mise exec. Run the line for your shell once, then open a new terminal.

Shell activation changes shell startup, so check that it is allowed on your machine before adding it. For PowerShell, Nushell, Elvish, Xonsh and IDE or CI shims, see the Shell setup page.

# 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

Learn the everyday commands

Most daily work uses a small set of commands. mise use records a tool in the project's mise.toml, mise install installs everything declared in the active config files, and mise env prints the resolved environment variables and PATH changes.

mise outdated lists tools with newer releases, and mise upgrade installs them.

  • mise use node@24: install a tool and record it in mise.toml
  • mise install: install all declared tools
  • mise exec -- <command>: run a command with the project's tools
  • mise run <task>: run a task
  • mise set KEY=value: set an environment variable
  • mise env: print resolved variables and PATH
  • mise ls --current: list active tool versions
  • mise outdated and mise upgrade: check and install newer releases

What people use it for

  • Running Node.js, Python or Rust projects that need different versions on the same machine.
  • Committing one mise.toml so a team and its CI use the same tool versions.
  • Replacing scattered .tool-versions, .nvmrc or .python-version files with one config, while still reading them once enabled.
  • Defining project tasks and environment variables in one place, such as a build task and a test task that depends on it.
  • Setting up a machine with mise bootstrap and mise dot apply for system packages, dotfiles and background services.

Frequently asked questions

How do I install mise?

On macOS or Linux, run curl -fsSL https://mise.run | sh. On Windows, run winget install jdx.mise. The README links to the Installing mise page for Homebrew, apt, dnf, Scoop and other package managers.

Is mise free and open source?

Yes. The project is licensed under the MIT licence, according to the README's licence badge and summary.

What is the difference between mise and asdf?

Both manage tool versions, and the source lists asdf as a comparable project. The source does not give a detailed feature comparison, so check each project's documentation for your needs.

Do I have to activate mise in my shell?

No. Activation is optional. Without it, you can run tools with mise exec. With activation, PATH and project variables update when you change directories, and you can call node directly.

What does mise.toml do?

It is the one file where a project declares its tools, environment variables and tasks. Committing it lets teammates and CI get the same setup with mise install or mise run.

Who should not use mise?

People who work on one project with a single tool and are happy with their current setup may gain little. Environments that do not allow installing a new binary and adding a shell hook may also not be a fit.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

mise suits developers who juggle several projects with different Node.js, Python or Rust versions, and teams that want a committed config file so everyone and CI use the same tools. If you only work on one project with a single tool, or you need a graphical app, your current setup or another tool may serve you better.

Install options & downloads