Developer Tools

mise: One File to End "Works on My Machine"

Manage Node.js, Python, environment variables and project tasks from one mise.toml, with locked versions across local machines and CI.

·
4 min read
·
AI-assisted

AI tooling disclosure

Generative AI materially contributed to this article.

Human review confirmed by the author.

mise: One File to End "Works on My Machine"

Pinning Node with nvm, Python with pyenv and environment variables with direnv means three tools and three setup steps for every new teammate. mise does all three from one mise.toml in your repo. Add a lockfile, and your laptop, your teammate's laptop and CI can use the exact same tool versions.

This post covers mise v2026.11.x (latest at the time of writing: v2026.11.12).

flowchart LR
    R[mise.toml and mise.lock in the repo] --> M([mise])
    M --> S[Same tools, env vars and tasks]
    S --> L[Your laptop]
    S --> N[New teammate]
    S --> C[CI]

Install and activate

curl -fsSL https://mise.run | sh            # or: brew install mise
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
mise doctor

For bash, use activate bash and ~/.bashrc. If a package manager installed mise, write mise instead of ~/.local/bin/mise. On Windows, run irm https://mise.run/powershell | iex in PowerShell.

Activation adds a hook that updates your PATH and environment on every prompt and directory change. Scripts and CI do not need it; use mise exec and mise run there.

Pin your tools

cd my-project
mise use node@24 [email protected]

mise use installs the tools if needed and records them in mise.toml:

[tools]
node = "24"
python = "3.13"

Commit it, and a teammate gets the tools you pinned by running mise install. Check what's active with mise ls --current.

Lock exact versions

"24" is a version prefix, so two machines can resolve it to different 24.x releases. A lockfile pins the resolved versions and, where supported, their download URLs and checksums:

# mise.toml
[settings]
lockfile = true
lockfile_platforms = ["linux-x64", "macos-arm64"]
mise lock                  # writes mise.lock
git add mise.toml mise.lock

With lockfile = true, mise also creates and updates the lockfile when it installs or upgrades tools. Commit it so teammates and CI can run:

mise install --locked

--locked installs from the lockfile and fails if a required entry is missing for the current platform. List every platform your team and CI use in lockfile_platforms; the current platform is added automatically.

Some npm and PyPI tools also produce dependency-graph files in .mise/locks/. Commit that directory alongside mise.lock when it is created. Remember that mise locks development tools, not your application dependencies, so keep committing files such as package-lock.json and uv.lock too.

New lockfiles from mise v2026.11.1 use format v4, which requires a compatible mise version. Make sure everyone sharing the lockfile uses v2026.11.1 or later.

To update, mise upgrade node installs the newest allowed version and updates the lockfile, while mise lock --bump updates the lockfile without installing. In CI, mise lock --check (v2026.11.10 and later) verifies that mise.lock matches mise.toml without writing anything or using the network.

Replace direnv

[env]
NODE_ENV = "development"
_.file = ".env"
_.path = "node_modules/.bin"

mise sets these when you enter the directory. Common .envrc lines and their equivalents:

.envrc

mise.toml

export NODE_ENV=development

NODE_ENV = "development" under [env]

dotenv

_.file = ".env" (a missing file is skipped)

PATH_add bin

_.path = "bin"

source_env_if_exists .envrc.local

Move machine-specific settings into mise.local.toml

source_up

Nothing; mise already merges config files from parent directories

layout python

_.python.venv = true

Keep secrets in an untracked mise.local.toml or .env, and add them to .gitignore:

.env
mise.local.toml
mise.local.lock

Add tasks

[tasks.test]
description = "Run the tests"
run = "npm test"

[tasks.build]
description = "Build the project"
depends = ["test"]
run = "npm run build"
sources = ["src/**/*.ts", "package.json"]
outputs = ["dist/**/*.js"]

mise run build installs any missing tools, sets the project's environment, runs test first, then builds. A task with sources and outputs is skipped while its outputs are up to date (--force overrides). mise tasks ls lists tasks, and mise run lint ::: test runs several in parallel.

Run it in CI

steps:
  - uses: actions/checkout@v7
  - uses: jdx/mise-action@v5
  - run: mise run test

The action installs mise and your tools, and automatically adds --locked when a mise.lock exists. On other CI systems, install mise with the same curl script, then run ~/.local/bin/mise install --locked.

Move off nvm, pyenv and direnv

  1. Pin the versions you use today.

  2. If you want to keep .nvmrc, enable it: mise ignores .nvmrc, .node-version and similar files until you opt in per tool, for example mise settings add idiomatic_version_file_enable_tools node --local. Older guides say they are read by default, which is no longer true.

  3. Move your .envrc lines into [env], then delete .envrc.

  4. Remove the nvm, pyenv and direnv lines from your shell startup file.

mise also reads asdf's .tool-versions, but tools listed only there are not locked, so move them into mise.toml.

Gotchas

  • A mise.toml can run code through hooks, [env] directives such as _.source, templates, tool postinstall options and tasks. Shell activation skips untrusted config and warns you to run mise trust. However, commands such as mise install, mise exec and mise run implicitly trust project configs they load, including parent directories. In CI, mise treats every config as trusted. Read unfamiliar configs before using them, and never expose secrets to untrusted pull requests. MISE_SAFE=1 lets automation read untrusted config for metadata and version-resolution tasks, but it is not a sandbox for running installs or tasks.

  • Keep mise updated. CVE-2026-35533 affected releases from v2026.2.18 up to, but not including, v2026.6.4. It involved a project config bypassing trust checks. It was fixed in v2026.6.4, so v2026.11.12 includes the fix. Keep mise updated through mise self-update or your package manager.

  • Very new releases may not resolve yet. When mise picks a version for a prefix such as 24 or for latest, it applies a default 24-hour delay to releases with known release dates. Exact versions and versions already in mise.lock are not delayed. You can raise the delay, for example minimum_release_age = "7d" under [settings].

  • Editors that don't read your shell startup files can use shims instead of activation, with some limits.

  • GitHub rate limits. If installs fail with a rate-limit error, give mise a GitHub token.

Where to start

Try it in one repo: pin Node, run mise lock, and commit both files. Add the CI step once the lockfile is in.

Comments(0)

Join the discussion by logging into your account.

No comments yet. Be the first to comment!

Anshu Pathak

Passionate developer sharing knowledge about modern web technologies and best practices.

Subscribe to Anshu Pathak's Newsletter

Direct email dispatches when new stories are published. Zero algorithms.