mise lock with mise.local.toml

[Sbou]

Hello,

I try to use the new feature to create a lock file by I have a bad behavior.

If I have a mise.local.toml file the following command create mise.local.lock file instead of mise.lock

mise lock

Following the documentation, it should create the local file only if I execute this command:

mise lock --local

Thanks,

[jstriebel]

Description from duplicate #8003, with reproducible example:

Problem

mise lock writes the lockfile matching the highest priority config (mise.local.lock) rather than the config that defines the tools (mise.toml).

Reproduction

mkdir test && cd test

cat > mise.toml << 'EOF'
[tools]
jq = "latest"
EOF

cat > mise.local.toml << 'EOF'
[env]
FOO = "bar"
EOF

mise lock
ls mise*.lock
# Output: mise.local.lock  ← mise.lock not created

Also, when when tools are in both files, everything goes into mise.local.lock.

Why this matters

Common pattern:

• mise.toml - committed, defines shared tools
• mise.local.toml - gitignored, personal overrides

Current behavior silently writes and reads gitignored mise.local.lock, so team members never get locked versions.

Suggested behavior

One lockfile per config file - tools defined in mise.toml → mise.lock, tools in mise.local.toml → mise.local.lock. This aligns with gitignore conventions and keeps shared tools locked in a committed file.

---

tested with mise 2026.2.3 linux-x64

[jdx]

Regarding the remaining points from @pikeas:

• mise install does not create lockfiles automatically — this is by design. You need to run mise lock to generate the lockfile initially. Once it exists, mise install and mise use will keep it updated. I've updated the docs to make this clearer since the previous wording ("automatic creation") was misleading.

• There is no mise.dev.lock — environment-specific tools (from mise.dev.toml, mise.test.toml, etc.) all go into the same mise.lock file tagged with an env field (e.g., env = ["dev"]). The only separate lockfile is mise.local.lock for mise.local.toml. This is described in the Environment-Specific Versions section of the docs.

This comment was generated by Claude Code.

[pikeas]

There is no mise.dev.lock — environment-specific tools (from mise.dev.toml, mise.test.toml, etc.) all go into the same mise.lock file tagged with an env field (e.g., env = ["dev"]). The only separate lockfile is mise.local.lock for mise.local.toml. This is described in the Environment-Specific Versions section of the docs.

This is contradicted by the description of #8012, which says:

mise lock now groups tools by their source config file and writes each to the corresponding lockfile

If the current behavior (only mise.lock and mise.local.lock) is intended, please consider separating out tools into corresponding lock files.

On a local checkout, MISE_ENV=dev mise install|use will update mise.lock with all of the dev tools. Then, a later CI build picks up all of these tools via mise install --locked and installs them into a prod build.

So, currently the only way to manage dev tools separately and with a lockfile is to put them in mise.local.toml, which the docs indicate is meant to be .gitignored.

There is no mise.dev.lock — environment-specific tools (from mise.dev.toml, mise.test.toml, etc.) all go into the same mise.lock file tagged with an env field (e.g., env = ["dev"])

With the latest version (2026.3.5), this does not appear to be the case:

$ rm mise.lock mise.local.lock
$ MISE_ENV=dev mise lock
...
Processing 18 tool(s): ...
$ grep env mise.lock
[no results]

As another reason to prefer per-env files, if this worked as described, it would mean that file-based build caching invalidated the prod mise.toml cache every time a dev tool is version bumped.

[jdx]

You're right that the #8012 PR description was misleading — "groups tools by their source config file and writes each to the corresponding lockfile" implies per-config lockfiles, but the actual behavior is a two-way split: mise.local.toml → mise.local.lock, everything else → mise.lock. I've updated the PR description to reflect this.

Environment-specific tools (from mise.dev.toml, mise.test.toml, etc.) go into mise.lock with env tags. #8519 (merged today, not yet released) fixed mise lock to correctly set these tags — previously only mise install/mise use did. This was the bug you hit when grep env mise.lock returned nothing.

Regarding the CI concern:

On a local checkout, MISE_ENV=dev mise install|use will update mise.lock with all of the dev tools. Then, a later CI build picks up all of these tools via mise install --locked and installs them into a prod build.

This shouldn't happen — tools are only installed if they're in an active config, and the lockfile is only used for version resolution. Without MISE_ENV=dev, mise.dev.toml isn't loaded, so its tools aren't installed regardless of what's in the lockfile. Here's a concrete example:

cat >mise.toml <<'EOF'
[tools]
tiny = "1"
EOF

cat >mise.dev.toml <<'EOF'
[tools]
"aqua:jqlang/jq" = "1.7.1"
EOF

# Generate lockfile with dev env
MISE_ENV=dev mise lock --platform linux-x64

# jq is tagged with env = ["dev"] in mise.lock
grep 'env = ' mise.lock
# => env = ["dev"]

# Without MISE_ENV, only base tools are visible
mise ls --current
# => tiny  1  ~/mise.toml  1

# With MISE_ENV=dev, both tools are visible
MISE_ENV=dev mise ls --current
# => aqua:jqlang/jq  1.7.1  ~/mise.dev.toml  1.7.1
# => tiny            1      ~/mise.toml       1

So CI running mise install --locked without MISE_ENV=dev will only install base tools — dev tools are skipped because mise.dev.toml isn't loaded.

This comment was generated by Claude Code.

[pikeas]

Thanks for the quick response (seems like it's really you but says generated by Claude Code)!

previously only mise install/mise use did.

Confirmed this after realizing I had a bad grep. FYI, the lockfile output includes a duplicate tools.jq block -

$ MISE_ENV=dev mise use jq@1.7.1
$ grep jq mise.lock
[[tools.jq]]
backend = "aqua:jqlang/jq"
<various tools.jq."platforms.[platform]" blocks>
[[tools.jq]]
backend = "aqua:jqlang/jq"

I'd also like to re-up the cache invalidation issue - that seems like a compelling reason to break out lockfiles per-env.

[pikeas]

I'd also like to re-up the cache invalidation issue - that seems like a compelling reason to break out lockfiles per-env.

#8523 looks like it addresses this, thanks!

FYI - neither the reference from that PR to here nor the attempt to close seem to have worked. Github may have different semantics for issues vs discussions.

[pikeas]

Issue is resolved by release 2026.3.7