
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 doctorFor 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.lockWith 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:
|
|
|---|---|
|
|
|
|
|
|
| Move machine-specific settings into |
| Nothing; mise already merges config files from parent directories |
|
|
Keep secrets in an untracked mise.local.toml or .env, and add them to .gitignore:
.env
mise.local.toml
mise.local.lockAdd 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 testThe 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
Pin the versions you use today.
If you want to keep
.nvmrc, enable it: mise ignores.nvmrc,.node-versionand similar files until you opt in per tool, for examplemise settings add idiomatic_version_file_enable_tools node --local. Older guides say they are read by default, which is no longer true.Move your
.envrclines into[env], then delete.envrc.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.tomlcan run code through hooks,[env]directives such as_.source, templates, toolpostinstalloptions and tasks. Shell activation skips untrusted config and warns you to runmise trust. However, commands such asmise install,mise execandmise runimplicitly 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=1lets 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-updateor your package manager.Very new releases may not resolve yet. When mise picks a version for a prefix such as
24or forlatest, it applies a default 24-hour delay to releases with known release dates. Exact versions and versions already inmise.lockare not delayed. You can raise the delay, for exampleminimum_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!