Mise Version Manager

There is no AI here. All content is human-authored and tested for accuracy.

Install Mise on Mac

Mise is a fast version manager written in Rust that manages multiple languages on your Mac. Install mise on Mac to replace nvm, pyenv, rbenv, and asdf. Here are instructions for Homebrew or curl installation, shell configuration, and troubleshooting.

Mise is a version manager that handles multiple programming languages and tools. Instead of installing separate version managers for each language (nvm for Node.js, pyenv for Python, rbenv for Ruby), you install one tool that manages them all.

Mise has actually grown to be more than a language version manager. It now serves as a tool for setting up a development environment on a per-project basis. Mise handles three things: language and development tool versions, environment variables through configuration files, and task runners for project automation.

You can install mise using Homebrew or curl, though Homebrew is recommended. Installing Mise is one step in setting up your Mac for development. See the full Mac setup roadmap for more.

Before you get started

You'll need a terminal application to install the mise version manager. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it's FREE and worth a try.

First steps to install Mise on Mac

First, check the macOS version. If you're running an older version, update macOS to the latest macOS version.

If you want to install mise via Homebrew (the recommended method for Mac), you need Homebrew installed. Homebrew is a package manager for macOS. Install Homebrew if you need it. Homebrew will install Xcode Command Line Tools if not already installed.

You will need to use a terminal application and edit configuration files in your home directory.

Install Mise via Homebrew

Homebrew is the easiest way to install Mise. Run the Homebrew installation command:

$ brew install mise

Verify the installation completed successfully.

$ mise --version

You should see the version number, such as mise 2026.3.6 or newer.

After installation, you need to activate mise in your shell, then verify everything with the mise doctor command. See below.

Where Homebrew places Mise

Homebrew downloads the appropriate version for your Mac. On Apple Silicon, you get the ARM64 version, installed to /opt/homebrew/bin/mise. On Intel Macs, you get the x86_64 version, installed to /usr/local/bin/mise. The Homebrew package directories should already be in your PATH. If you get an error command not found: mise, check your Mac PATH. If Homebrew itself is not found, see command not found: brew.

This differs from the curl installation method, which places mise in ~/.local/bin. The Homebrew location is preferred for Mac users because it conforms with macOS conventions and Homebrew's package management.

Install Mise via curl

If you prefer not to use Homebrew, mise provides two curl install scripts. Both place the binary at ~/.local/bin/mise.

Basic install script

The basic script installs the binary only:

$ curl https://mise.run | sh

This downloads and installs the mise binary to ~/.local/bin/mise. It does not modify your shell configuration. You must set up activation yourself (see below).

Zsh install script (recommended curl method)

The zsh-specific script installs the binary and sets up activation automatically:

$ curl https://mise.run/zsh | sh

This runs the same basic install, then appends the activation line to your ~/.zshrc:

eval "$($HOME/.local/bin/mise activate zsh)" # added by https://mise.run/zsh

If you use the zsh script, activation is already configured. Restart your terminal (or run source ~/.zshrc) for it to take effect.

Verify the curl installation

After running either curl script, verify the installation by using the full path to the binary:

$ ~/.local/bin/mise --version

You should see the version number, such as mise 2026.3.6 or newer. Note that typing just mise --version will not work yet if you used the basic script, because ~/.local/bin is not on your PATH by default. The activation step handles this (see below).

What the basic install script does

The basic install script does not modify your shell configuration or PATH. It performs four steps: it detects your OS (macOS or Linux) and CPU architecture (Intel or Apple Silicon), downloads a specific pinned version of the mise binary from mise.jdx.dev, verifies the download against a SHA-256 checksum hardcoded in the script, and places the binary at ~/.local/bin/mise.

After installation, the script prints instructions for activating mise in your shell but does not run them. You do not need to add ~/.local/bin to your PATH manually. The activation line uses the full path to the binary, and mise activate prepends the binary's directory to PATH automatically as a side effect. See the activation section below.

Option to customize the installation location

By default, mise installs to ~/.local/bin. Install to that directory (or Homebrew's opt/homebrew/bin on Apple Silicon) to keep maintenance and troubleshooting simple.

If you really want a different location, you can set the MISE_INSTALL_PATH environment variable before running the installation script.

$ MISE_INSTALL_PATH=/custom/path curl https://mise.run | sh

Replace /custom/path with your preferred directory. Make sure the directory exists and you have write permissions. After installation, you'll need to add this custom directory to your Mac PATH manually.

Activate Mise in your shell

After installation, you need to activate mise in your shell so that the mise command and managed tools work automatically. Activation configures your shell so mise updates PATH and environment variables automatically when your shell starts. If you used the mise.run/zsh curl script, activation is already set up and you can skip to the verification step below.

Add the activation command to your shell configuration file. For zsh (the macOS default), use a terminal text editor to edit your ~/.zshrc file and add this line.

If you installed with Homebrew:

eval "$(mise activate zsh)"

If you installed with the basic curl script, use the full path to the binary. You do not need to add ~/.local/bin to your PATH separately. The mise activate output detects that the binary's directory is not on PATH and prepends it automatically each time the shell starts.

eval "$($HOME/.local/bin/mise activate zsh)"

After editing, close and reopen your terminal window to reload your shell configuration so the changes take effect. Or enter:

$ source ~/.zshrc

For troubleshooting and a deeper understanding of what the activation line does under the hood, see How Mise Works.

If you use a non-interactive environment like CI/CD

Mise offers two different activation modes. PATH mode, which you just set up, is the recommended approach for local development on your Mac. When your shell starts, mise updates PATH and environment variables so tools managed by mise work automatically.

Shims mode is an alternative that creates small wrapper scripts in ~/.local/share/mise/shims. These wrappers are useful for non-interactive environments like CI/CD pipelines, IDEs, or scripts. If you need to use shims, see see How Mise Works and the shims mode documentation.

Mise Doctor

Check that mise is properly set up with its diagnostic tool.

$ mise doctor

The command will inform you, "mise is not activated," or "no problems found." It also shows configuration details and your current PATH setting.

Look for any warnings in the output. Common warnings include "Shims not on PATH" (usually means activation didn't complete) or "Ignored config files" (means a configuration file wasn't trusted). If you see warnings, the troubleshooting section below provides solutions.

Where Mise stores data

Mise creates several directories to store data, configuration, and cache files. Understanding these locations helps with troubleshooting and managing your setup.

Global configuration lives in ~/.config/mise/config.toml. This file stores your default tool versions and environment variables that apply across all projects. You can edit this file directly or use mise commands to modify it.

Tool installations are stored in ~/.local/share/mise/installs/. Each tool version has its own subdirectory. For example, Node.js 24.0.0 is stored in ~/.local/share/mise/installs/node/24.0.0. This directory grows as you install more tools and versions.

Mise stores cache files in ~/Library/Caches/mise/. This location follows macOS conventions. Cache files speed up operations and are safe to delete if you need to free space.

State information is stored in ~/.local/state/mise/. This directory tracks runtime state and is separate from configuration.

You can customize these locations by setting environment variables. $MISE_CONFIG_DIR controls the configuration directory, $MISE_DATA_DIR controls where tools are installed, and $MISE_CACHE_DIR controls the cache directory.

Common installation errors

This section covers the most common problems and how to fix them.

Fix GPG signature verification failures

When installing certain tools, especially Node.js, you might see an error about GPG signature verification. This occurs more frequently on macOS after system updates.

The solution is to reset your GPG directory.

$ gpg --refresh-keys

This usually resolves the issue.

Fix activation not working after installation

If mise --version works but node or other tools don't, your shell activation likely didn't complete.

Check if mise is in your PATH.

$ echo $PATH

Look for the mise binary program path in the output. For Homebrew installs, you should see /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel). For curl installs, you should see ~/.local/bin, which is added to PATH automatically by the activation line each time the shell starts. If these paths are missing, activation did not complete. See How Mise Works for details on how activation modifies PATH.

Fix wrong version being used

If you install a tool but the old version still runs, another version manager or a conflicting PATH entry might be intercepting the command.

Check all versions in your PATH. For example:

$ which -a node

This command shows every node binary program in your PATH. If you see multiple results, something else is overriding mise.

Verify mise is properly activated.

$ echo $PATH

The mise binary program path should appear early in the output, before other version managers. If it appears later, something else is interfering. Check your .zshrc file for activation of other tools like nvm or pyenv, and remove those lines.

Troubleshooting

Several mise commands help diagnose and fix problems.

  • mise doctor shows detailed diagnostic information and warnings about your setup. Run this first when something isn't working.

  • mise cache clean removes downloaded packages and temporary build files. Use this if you're low on disk space or suspect cached files are causing problems.

  • mise trust marks configuration files as trusted. New project configurations require explicit trust for security. Run this in a project directory if mise warns about untrusted configuration.

How to use Mise

With mise installed and activated, your next step is installing programming languages. Mise manages multiple languages from a .mise.toml configuration file in every project directory.

Here are usage instructions for popular languages:

Each guide covers installation, version switching, and project-level configuration.

Mise supports dozens of other languages and tools. Use mise ls-remote --all to discover available tools and versions (there are hundreds available!).

Once you have languages set up, explore Mise Configuration to learn how project .mise.toml files control versions, environment variables, and settings across projects. You can also use Mise Tasks to define project tasks similar to Makefiles or npm scripts with a built-in task runner.

If you're migrating from the asdf version manager, see Mise vs asdf for a comparison and migration steps. If you run into problems, see command not found: mise for troubleshooting. If you ever need to remove mise completely, see Uninstall Mise.

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.