Mops v3 Turns the Motoko Build Into a Committed Artifact

Mops v3, released on August 20, introduces a meaningful shift in how Motoko projects define a build. The package manager now owns the versions of the compiler and supporting tools used by the project, while dfx integration is removed.

The central change is the new [toolchain] section in mops.toml. Projects can pin moc, PocketIC, Wasmtime, Lintoko, and Binaryen’s wasm-opt. Commands that compile require a pinned Motoko compiler; replica tests and related checks also require a PocketIC pin. An unpinned toolchain now produces an error instead of silently selecting a default.

That matters because a canister’s source tree is not the whole build input. Compiler behavior, replica behavior, and Wasm optimization can all affect the resulting artifact. Mops says that an unpinned wasm-opt previously allowed a network lookup to rewrite the manifest and change builds across Binaryen releases. In v3, the optimizer must be pinned, and an optimization failure fails the build rather than quietly leaving an unoptimized module.

The release also gives CI a clearer boundary. Normal commands maintain mops.lock; CI can use --locked, which requires an up-to-date lockfile and never writes one. The lockfile records resolved versions, per-file hashes for registry packages, and commits plus content hashes for GitHub dependencies. A branch or tag such as #main is resolved once and then fetched by commit, so a moved ref cannot silently change a locked build.

The security model is deliberately split. Package files are checked as they arrive, preventing a corrupted download from entering the cache. A full audit of files already on disk is now an explicit mops verify operation. Developers should therefore treat the committed lockfile as a reviewable build input, and use --locked in CI when mutation must be prohibited.

The breaking part is the dfx boundary. Mops no longer provides mops toolchain init or the moc-wrapper, and it no longer writes DFX_MOC_PATH into GitHub Actions. A workflow can therefore remain green while mops check uses one compiler and dfx build uses another. Teams staying on dfx must set and maintain the compiler path themselves; the supported ICP-oriented path is a build recipe that invokes mops build.

There is one migration detail that can look like a regression: benchmark baselines may change because Mops v3 always uses PocketIC for its replica-oriented commands. A first comparison can show different instruction or heap counts simply because the measuring instrument changed. Re-recording the baseline is part of the migration, not evidence by itself that the canister became slower.

For ICP teams, the practical checklist is short: pin the toolchain, commit mops.lock, add --locked to reproducible CI jobs, inspect any DFX_MOC_PATH setup, and rerun benchmark baselines after moving from an implicit dfx replica. The broader lesson is that reproducibility now includes the tools that produce and measure a canister, not only the Motoko dependencies it imports.

Editorial caveat: The installation figures cited in the release announcement are maintainer-reported and are not independently reproduced in this article. The Mops documentation also says lockfile speedups are most noticeable when packages are not already cached.