Getting started

By the end of this guide, you'll have a project with a managed tool, an environment variable, and a task you can run. Shell activation is optional: the first examples work without changing your shell configuration.

Already installed mise for an existing project? Review its mise.toml, then run mise install from the project directory. Use mise tasks ls to see its tasks.

1. Install mise CLI

See installing mise for other ways to install mise (Homebrew, MacPorts, apt, Nix, and more).

curl https://mise.run | sh

The installer places the mise executable in ~/.local/bin.

Verify the installation:

~/.local/bin/mise --version
# mise 2026.x.x

• ~/.local/bin does not need to be in PATH. mise will automatically add its own directory to PATH when activated.

To customize where mise stores downloaded tools and other data, see directories.

2. Run your first tool

Use mise exec to run a command with a specific tool version:

mise exec node@24 -- node --version

By default, mise downloads the tool if needed, then runs the command after --. This does not add Node.js to your project configuration or change your current shell's environment. The output starts with v24.; the patch version may vary.

TIP

If mise isn't on PATH yet, use ~/.local/bin/mise instead on macOS or Linux. Activation in step 4 adds mise to your shell's PATH.

3. Set up a project

Create a directory for this example, or use an existing project directory:

mkdir mise-example
cd mise-example
mise use node@24

mise use installs the tool and writes its version request to mise.toml. Unlike mise install, it also changes your configuration.

Set an environment variable

Edit the generated mise.toml to contain:

mise.toml

[tools]
node = "24"

[env]
NODE_ENV = "development"

Run a command with both the configured tool and environment:

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

You can also load variables from a .env file.

Run a task

Add this section to the same mise.toml:

mise.toml

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

mise run hello

The output includes a Node.js version starting with v24. and development. Tasks get the project's tools and environment automatically. By default, mise run installs missing configured tools before running the task.

Commit mise.toml so teammates and CI can use the same configuration. The version request "24" selects a release in the Node.js 24 series; it is not an exact pin. See lockfiles to share resolved versions across machines.

Project configuration or global defaults?

Command	What it does
mise use node@24	Installs Node.js and saves the version request in the project config. Run it from your project directory.
mise use --global node@24	Installs Node.js and saves a personal default in the global config.
mise install	Installs tools already declared in your configuration.
mise exec -- node --version	Runs one command with the project's tools and environment.
mise run hello	Runs a named task with the project's tools and environment.

Project configuration can override global defaults. Use mise config ls to see which files are active and mise ls --current to inspect the selected tools.

Trusting config files

Review configuration from other people before running it: tasks, hooks, and some environment directives can execute code. Use mise trust to explicitly trust a config you've reviewed.

In normal mode, commands that execute project behavior, including mise install, mise exec, and mise run, automatically trust the active config. With paranoid mode, non-global configs require explicit trust. See mise trust for details.

4. Activate mise optional

mise exec works great for one-off commands, but for interactive shells you'll probably want to activate mise so tools and environment variables are loaded automatically.

There are two approaches:

• mise activate — updates your PATH and environment every time your prompt runs. Recommended for interactive shells.
• Shims — command entry points that select tool versions. Useful for editors and other programs that do not load your shell config. Shims don't support all features of mise activate.

You can skip both and use mise exec or mise run to load the project environment explicitly, including in CI and scripts.

Here is how to activate mise for your shell:

bash

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

zsh

echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc

fish

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

Restart your shell session after modifying your rc file. Run mise dr|doctor to verify everything is set up correctly.

With mise activated, tools are available directly on PATH:

mise use --global node@24
node -v
# v24.x.x

When you ran mise use --global node@24, mise updated your global config:

~/.config/mise/config.toml

[tools]
node = "24"

5. Find more tools

Use the registry to find tool names such as node, python, jq, and ripgrep. Most of the time, the name is all you need:

mise use ripgrep
mise exec -- rg --version

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

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

Some backends require another runtime or package manager. Check the backend guide before using a new ecosystem.

6. Next steps

• Keep working in a project: follow the walkthrough for configuration overrides, upgrades, and daily commands.
• Write build and test commands: see tasks.
• Use mise outside a terminal: set up your editor or CI pipeline.
• Set up a machine: use bootstrap for declared system packages, dotfiles, and services.

Set up autocompletion

Enable shell completions to complete tools, versions, and task names.

If something doesn't 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 restart your shell. See troubleshooting for other common problems.

GitHub API rate limiting

If an error reports GitHub API rate limiting, configure a GitHub token.

Shell Feature Compatibility

Not all shells support every mise feature:

Feature	Bash	Zsh	Fish	Nushell	Elvish	Xonsh	PowerShell
mise activate	Yes	Yes	Yes	Yes	Yes	Yes	Yes
mise shell	Yes	Yes	Yes	Yes	Yes	Yes	Yes
Shell aliases ([shell_alias])	Yes	Yes	Yes	No	No	Yes	No
chpwd hook	Yes	Yes	Yes	Yes	Yes	Yes	Yes