What does `cargo install` build, where does Cargo put the installed binaries, and why does `--locked` matter there?
answer
- binaries only, never libraries
- an optimized build by default
- the installation root's bin folder
- the shipped lockfile is ignored
basics
~20 scargo install builds a package's binaries with the release profile and copies them into the installation root's bin folder, $HOME/.cargo/bin by default. It ignores the package's own Cargo.lock and resolves dependencies afresh unless you pass --locked.
solid answer
~40 s`cargo install` fetches a package, from crates.io by default or from `--git` or `--path`, and builds only its executable targets, binaries by default and examples if asked, using the **release** profile. The executables go into the installation root's `bin` folder, where the root is chosen by `--root`, then `CARGO_INSTALL_ROOT`, the `install.root` config value, `CARGO_HOME`, and finally `$HOME/.cargo`. The trap is the lockfile: by default Cargo ignores the `Cargo.lock` shipped with the package and resolves dependencies again, possibly picking releases published after the tool was. `--locked` uses the packaged lockfile instead, giving a reproducible install and dodging a newly broken dependency, at the cost of also skipping dependency fixes. `--debug` or `--profile` changes the profile, and `--force` reinstalls.
go deeper
Recall that cargo install builds a tool's binaries in release mode and puts them in $HOME/.cargo/bin by default, and that it is not how you add a library to a project.
Explain the installation-root precedence and the lockfile rule: the shipped Cargo.lock is ignored unless --locked is passed, and what each choice gains and costs.
Show how you keep tool installs reproducible and fast in CI: --locked, pinned versions, a cached CARGO_TARGET_DIR, and knowing local config only applies with --path.
Weigh reproducible tool installs against picking up dependency fixes, and decide whether a team installs tools with --locked from crates.io or ships prebuilt binaries.
## What `cargo install` builds `cargo install` is how Rust developers put command-line tools on their machine: a formatter for another language, a code generator, or one of the many `cargo-*` subcommands. It is not a dependency manager for a project; adding a library to `Cargo.toml` is `cargo add`. The command: - fetches the package from crates.io by default, or from a git repository with `--git URL`, or from a local directory with `--path DIR`; - builds only the package's **executable** targets. The Cargo docs state that "only packages which have executable [[bin]] or [[example]] targets can be installed", and by default only binaries, not examples, are installed; - uses the **release** profile, so the tool is optimized. `--debug` builds an unoptimized binary instead, and `--profile NAME` picks any profile by name. Installing the scratch package behind this answer printed ``Finished `release` profile [optimized]`` without any profile flag. ## Where the binaries go Cargo copies the executables into the `bin` folder of the **installation root**, chosen in this order of precedence: 1. the `--root DIR` option; 2. the `CARGO_INSTALL_ROOT` environment variable; 3. the `install.root` config value; 4. the `CARGO_HOME` environment variable; 5. `$HOME/.cargo`. With nothing set, the result is `$HOME/.cargo/bin`, which rustup normally adds to `PATH`. When the chosen folder is not on `PATH`, Cargo says so with a warning to "be sure to add" it. Any executable named `cargo-NAME` on `PATH` then also works as `cargo NAME`; that discovery rule, and which third-party subcommands are worth installing, belong to the material on Cargo's third-party subcommands. ## The lockfile trap The Cargo docs are explicit: "By default, the Cargo.lock file that is included with the package will be ignored." Cargo recomputes the dependency versions, "possibly using newer versions that have been released since the package was published." | | Plain `cargo install` | `cargo install --locked` | |---|---|---| | Dependency versions | resolved fresh, newest compatible | those in the packaged `Cargo.lock` | | Same command, a month apart | may build different dependency versions | builds the same versions, when the package ships a lockfile | | A dependency release that breaks the build | can break your install | avoided | | Fixes released since publishing | picked up | not picked up | Both columns have a cost. `--locked` is the safer default for CI images and team setup scripts, where "it installed yesterday" must stay true, and the Cargo docs name it for "ensuring reproducible builds". A plain install gets dependency fixes the tool's author has not released yet, along with any regressions. ## Choosing what to install A bare `cargo install NAME` installs the newest release of the crate. `cargo install [email protected]` or `--version 1.4.2` installs that exact release: the Cargo docs point out that a version without an operator "is not treated as a caret requirement like Cargo dependencies are". A requirement such as `--version ~1.4` picks the newest matching release instead. For git sources, `--branch`, `--tag` or `--rev` choose the commit, and `--bin NAME` or `--example NAME` installs a single executable from a package that has several. ## Reinstalling and listing Running `cargo install` again for a package already installed reinstalls it only when something relevant changed: the package version or source, the set of binary names, the chosen features, the profile, or the target. Installing with `--path` always builds and installs, unless the binaries conflict with another package's. `--force` reinstalls regardless, which is useful after a compiler upgrade. `cargo install --list` shows what is installed, and `cargo uninstall` removes a package's binaries. ## Build location and configuration For crates.io and git sources, the build happens in a **temporary target directory**, so nothing is cached between installs. Setting `CARGO_TARGET_DIR` to a cached path changes that, which the Cargo docs suggest for CI. `cargo install` also ignores the current project's `.cargo/config.toml`, because it "operates on system or user level, not project level": configuration discovery begins at `$CARGO_HOME/config.toml`. The exception is `--path DIR`, where discovery starts at that directory's `.cargo/config.toml`. ## Mistakes interviewers listen for - Adding `--release` out of habit, or believing the default is a debug build. - Expecting the published `Cargo.lock` to be honoured without `--locked`. - Trying to `cargo install` a library-only crate to use it in a project. - Wondering why a project's local Cargo config did not apply to a crates.io install.
- Why might `cargo install` of a tool's same version fail today when it installed cleanly last month?Without `--locked`, Cargo ignores the tool's packaged `Cargo.lock` and resolves its dependencies fresh, so today's install may pick a dependency release published since then that no longer builds on your system or toolchain. `cargo install --locked` rebuilds with the versions the author published against, when the package ships a lockfile.
- How do you avoid recompiling the same tool from scratch on every CI run?Installs from crates.io or git build in a temporary target directory, so nothing survives between runs. Point `CARGO_TARGET_DIR` at a cached directory to keep build artifacts, and cache the installation root's `bin` folder too: re-running `cargo install` for a version already installed with the same features and profile does not rebuild it.
- Does `cargo install --path .` use the project's `.cargo/config.toml`?Yes. Normally `cargo install` works at user level and begins configuration discovery at `$CARGO_HOME/config.toml`, ignoring the current project's config. With `--path DIR`, discovery starts at `DIR/.cargo/config.toml`, so settings such as source replacement in that directory apply.
- cargo install builds a debug binary unless you add --release
- cargo install always builds with the Cargo.lock the crate was published with
- cargo install adds the crate as a dependency in Cargo.toml
- cargo install can install a library-only crate for use in other projects
- --locked makes cargo install fetch the newest dependency versions