--- title: "mise: One File to End \"Works on My Machine\"" author: "Anshu Pathak" published: "2026-11-22T05:02:18.283Z" updated: "2026-11-22T05:02:18.283Z" url: "https://zyvop.com/mise-one-file-to-end-works-on-my-machine-3w6kp" canonical: "https://zyvop.com/mise-one-file-to-end-works-on-my-machine-3w6kp" tags: ["mise","Python","developer tools","DevOps","nodejs"] --- # 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. ![Cover image]() 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). ```mermaid 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 ```bash 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 ```bash cd my-project mise use node@24 python@3.13 ``` `mise use` installs the tools if needed and records them in `mise.toml`: ```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: ```toml # mise.toml [settings] lockfile = true lockfile_platforms = ["linux-x64", "macos-arm64"] ``` ```bash 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: ```bash 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 ```toml [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`: ```gitignore .env mise.local.toml mise.local.lock ``` ## Add tasks ```toml [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 ```yaml 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.