Manage Node, Python and Go versions per project with mise

Tools used

• 

  mise

  CLI tool for managing development environments with version-controlled tools, environment variables, and tasks

  35.5kRust

Before you start

• -macOS, Linux or Windows; this guide uses bash, zsh or fish
• -curl for the install script, or Homebrew, apt, dnf or another package manager
• -Remove or plan to remove nvm, asdf or pyenv lines from your shell rc file (step 8)

Steps

1. 1Step 1: Install mise

   The official script installs a single binary to ~/.local/bin/mise. Homebrew and most Linux package managers also ship mise; the project notes that the Homebrew build is separate from its release binaries.

   sh

   $ curl https://mise.run | sh
   $ ~/.local/bin/mise --version

   sh

   $ brew install mise

2. 2Step 2: Activate mise in your shell

   Activation adds a hook that updates PATH and environment variables at each prompt, so the versions follow you between directories. Put it in the rc file your interactive shell reads, not ~/.bash_profile or ~/.zprofile. Use the full path ~/.local/bin/mise if that directory is not on PATH yet.

   Open a new shell and run mise doctor; it should report activated: yes. With Homebrew and fish, mise activates itself and you can skip this step.

   zsh

   # ~/.zshrc
   $ eval "$(mise activate zsh)"

   bash

   # ~/.bashrc
   $ eval "$(mise activate bash)"

   fish

   # ~/.config/fish/config.fish
   $ mise activate fish | source

   sh

   $ mise doctor

3. 3Step 3: Pin versions for a project with mise use

   From the project root, mise use installs each tool and writes the request to mise.toml. A partial version such as 22 selects the newest installed or available 22.x release; it is not an exact pin. Add --pin to write the full resolved version instead.

   For Go 1.20 and older, where 1.20 is itself a release, use go@prefix:1.20 to get the latest 1.20.x.

   sh

   $ cd ~/code/my-app
   $ mise use node@22 python@3.12 go@1.23

   toml

   # mise.toml (written by the command above)
   [tools]
   go = "1.23"
   node = "22"
   python = "3.12"

   sh

   $ mise ls --current
   $ node --version

4. 4Step 4: Install a project's tools after cloning

   Commit mise.toml. On another machine, or for a teammate, mise install installs everything the config declares without changing it. Review config files from other people first: tasks, hooks and some [env] directives can run code, and mise trust marks a reviewed file as trusted.

   sh

   $ git clone https://github.com/example/my-app && cd my-app
   $ mise install
   $ mise exec -- node --version

5. 5Step 5: Choose between mise.toml and .tool-versions

   mise.toml is the native format and the one to use unless teammates still run asdf. It supports [env], [tasks] and tool options. .tool-versions is asdf's format; mise reads it and can write it with --path, using the asdf names (nodejs, golang). If both files exist in a directory, mise.toml wins for the tools it declares.

   mise can also read per-language files such as .nvmrc, .node-version and .python-version, but that is off by default. Enable it per tool.

   sh

   # keep a shared .tool-versions for asdf users
   $ mise use --path .tool-versions --pin node@22

   sh

   # read .nvmrc / .node-version and .python-version
   $ mise settings add idiomatic_version_file_enable_tools node
   $ mise settings add idiomatic_version_file_enable_tools python

6. 6Step 6: Set global defaults

   mise use -g writes to ~/.config/mise/config.toml. Those versions apply anywhere a project config does not override them, for example in your home directory or in repos without a mise.toml.

   sh

   $ mise use -g node@lts python@3.12 go@latest

7. 7Step 7: Add environment variables and tasks

   The [env] table sets variables while you are in the project; _.file loads a .env file, and for Python _.python.venv creates and activates a virtualenv. [tasks] defines commands you run with mise run, which get the project's tools and environment.

   toml

   # mise.toml
   [env]
   NODE_ENV = "development"
   _.file = ".env"
   _.python.venv = { path = ".venv", create = true }
   
   [tasks.test]
   description = "Run the test suite"
   run = "npm test"

   sh

   $ mise run test
   $ mise tasks ls

8. 8Step 8: Migrate from asdf or nvm

   From asdf: mise reads existing .tool-versions files, so run mise install in each project and check it with mise exec -- node --version. mise does not reuse asdf's install directory. Once that works, delete the asdf lines and its shims directory from PATH in your rc file.

   From nvm: enable .nvmrc support (step 5), set a default with mise use -g node@lts, and remove the NVM_DIR export and the line that sources nvm.sh. Globally installed npm packages do not carry over; reinstall the ones you need.

   Open a new shell and confirm with mise doctor and type -a node.