cargo install --locked: Reproducible Tool Installs
cargo install --locked builds and installs a binary crate using the versions in its bundled Cargo.lock, so the install is reproducible instead of resolving fresh dependency versions.
Installing CI tools like cargo-nextest or sqlx-cli without --locked can pull newer transitive deps that fail to build. --locked makes the install deterministic.
What it does
cargo install compiles a binary crate and copies the executables into ~/.cargo/bin (or --root). --locked tells it to use the crate's published Cargo.lock rather than recomputing the dependency graph, which avoids surprise upgrades that break the build.
Common usage
cargo install cargo-nextest --locked
cargo install sqlx-cli --version 0.7.4 --locked
cargo install --locked --root /usr/local mytool
cargo install --git https://github.com/owner/repo --lockedFlags
| Flag | What it does |
|---|---|
| --locked | Use the crate's Cargo.lock; do not update dependencies |
| --version <ver> | Install a specific version |
| --root <dir> | Install into a custom prefix instead of ~/.cargo |
| --git <url> | Install from a git repository |
| --force | Reinstall even if the same version is present |
| --no-default-features | Disable default features of the tool |
In CI
Cache ~/.cargo/bin (and ~/.cargo/registry) so installed tools persist across jobs and avoid recompiling. Pin both --version and --locked for fully reproducible toolchains. For prebuilt speed, many tools also ship installers like cargo-binstall that download a binary instead of compiling.
Common errors in CI
"error: the lock file ... needs to be updated but --locked was passed" means the crate's Cargo.lock is incompatible with your toolchain; try a different --version or a newer rustc. "error: binary X already exists in destination" means re-running without --force. "error: failed to compile X, intermediate artifacts can be found at ..." points at a build failure in a dependency.