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's now 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 it's 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 mise: command not found, check your Mac PATH. If Homebrew itself is not found, see Fix zsh: 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

The curl method installs mise directly from the official installation script. This approach works on any Mac if you don't want to use Homebrew.

Download and run the official mise installation script.

$ curl https://mise.run | sh

This command downloads a shell script and pipes it directly to the shell for execution. The script installs mise to ~/.local/bin/mise by default. Verify the installation.

$ mise --version

You should see the version number confirming successful installation. Continue to the shell activation section below, then verify everything with the mise doctor command.

What the Mise Install Script Does

The install script does not set up your shell or modify your PATH. It performs four steps:

  1. Detects your OS (macOS or Linux) and CPU architecture (Intel or Apple Silicon).
  2. Downloads a specific pinned version of the mise binary from mise.jdx.dev.
  3. Verifies the download against a SHA-256 checksum hardcoded in the script.
  4. 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 still need to add the activation line to your shell configuration.

If you can run mise immediately after installation without reopening your terminal, it means ~/.local/bin is already on your PATH, likely added by a previous tool installation. If not, you'll need to add ~/.local/bin to your Mac PATH manually.

Customize the installation location

By default, mise installs to ~/.local/bin. If you prefer a different location, 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.

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. See Mac shell configuration to learn how to edit a shell configuration file.

eval "$(mise activate zsh)"

If you installed with curl and not Homebrew, use the full path to the mise binary program.

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

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 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

These commands rename your existing GPG directory and create a fresh one. GPG will download updated keys the next time it is needed. 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. If you don't see /opt/homebrew/bin (Apple Silicon with Homebrew), /usr/local/bin (Intel with Homebrew), or ~/.local/bin (curl installation), activation didn't work.

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 Fix mise: command not found 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.