Skip to main content
Version: 3.x

Toolchain Management with Mops

Mops simplifies toolchain management for Motoko projects, allowing you to specify exact versions of each tool in the mops.toml file for each project.

When you run mops install command, Mops will install the specified version of each tool.

Available tools​

Specifying tool versions​

Option 1: Use mops toolchain use command​

You can use mops toolchain use command to install specific tool version and update mops.toml file.

mops toolchain use moc 1.15.1
mops toolchain use wasmtime 41.0.0
mops toolchain use pocket-ic 15.0.0
mops toolchain use lintoko 0.11.0
mops toolchain use wasm-opt 131

No need to run mops install when you use mops toolchain use command.

Option 2: Edit mops.toml file​

You can manually edit mops.toml file to specify exact versions of each tool.

[toolchain]
moc = "1.15.1"
wasmtime = "41.0.0"
lintoko = "0.11.0"
pocket-ic = "15.0.0"
wasm-opt = "131"

You need to run mops install command when you edit mops.toml file manually.

pocket-ic versions​

Replica tests, benchmarks, --check-deploy, and mops toolchain bin pocket-ic all require an explicit [toolchain] pocket-ic pin — there is no default. Unpinned, they error naming mops toolchain use pocket-ic 15.0.0. The version in that hint is not a runtime fallback; it can move when a newer server is the one to recommend. The one exception is MOPS_POCKET_IC_URL: when it points at an already-running PocketIC server, no pin is needed, an existing pin is ignored with a warning, and no binary is downloaded.

Any version from 9.0.0 up can be pinned (mops toolchain use pocket-ic latest resolves and pins the newest release). Mops keeps no list of blessed versions — as with moc, wasmtime and lintoko, the version you pin is the version you get. A literal pocket-ic = "latest" written into mops.toml by hand does not work — the field takes a concrete version or a file path.

Pins below 9.0.0 are rejected with a migration message. They worked in Mops 2.x through a second, legacy PocketIC client, which 3.0.0 removed; without the check, upgrading with an old pin would fail with an opaque timeout from the client instead. Run mops toolchain use pocket-ic 15.0.0.

Option 3: Use explicit file paths​

You can also specify file paths to toolchain binaries. This is useful when building a tool from source. File paths must start with /, ./, or ../.

[toolchain]
moc = "./tools/moc"

or

[toolchain]
moc = "/usr/local/bin/moc"
lintoko = "../custom-lintoko/bin/lintoko"

Toolchain cache​

Downloaded tools live under the mops cache directory: ~/.cache/mops/<tool>/<version> on Linux, ~/Library/Caches/mops/<tool>/<version> on macOS, or $XDG_CACHE_HOME/mops/<tool>/<version> when that variable is set. A version is extracted into a staging directory and renamed into place, so the cache never holds a half-extracted tool.

Concurrent mops processes that need the same uninstalled version — for example a build tool running one mops build <canister> per canister — serialize on an advisory lock at <cache>/<tool>/<version>.lock. The waiting processes print Waiting for another mops process to install moc 1.15.1... on stderr and continue once the install finishes. If the installing process was killed, the lock is reclaimed after a minute; remove the .lock directory to recover sooner.

Toolchain management commands​