CARGO-INSTALL-UPDATE(1)

🎀 CARGO-INSTALL-UPDATE(1) 🎀

Hey bestie, welcome to the CARGO-INSTALL-UPDATE(1) page from the General Commands Manual. It's giving “Cargo subcommand that keeps your installed executables from being stale” energy, and honestly? Iconic. 💅

💖 NAME 💖

cargo-install-update — Cargo subcommand for checking and applying updates to installed executables. Slay.

✨ SYNOPSIS ✨

cargo install-update [OPTIONS] [PACKAGE...]

🦋 DESCRIPTION 🦋

Cargo subcommand for checking and applying updates to installed executables. That's the whole vibe.

This was mostly built out of a frustration with periodically checking for updates for my cargo-installed executables, which was long and boring. Literally same, bestie 😭.

Updates packages from the main repository and git repositories.

See cargo-install-update-config(1) for further configuring updates, and the metadata from cargo install that may be preserved by default.

The CARGO_INSTALL_OPTS environment variable can be set, containing options to forward to the end of cargo install invocations' argument lists. Note, that cargo-install-update-config(1) is preferred in the general case.

If cargo-binstall (>=0.13.1) is available in the PATH, -r was not given, CARGO_INSTALL_OPTS is empty, the package is in the default registry, and has no non-default configuration, it will be used to install the package instead.

Exit values and possible errors:

-1 - cargo subprocess was terminated by a signal (Linux-only)
1  - option parsing error
2  - registry repository error
X  - bubbled-up cargo install exit value

🌸 OPTIONS 🌸

• -a, --all — Update all currently installed executables. Required if list of packages not given.
• [PACKAGE...] — List of packages to update in the [(registry_url):]package_name[:version] format. Registry defaults to the default crates.io registry, and can be a name from ~/.cargo/config. If specified in addition to --all, will add the specified packages to the update list (useful, e.g., in conjunction with --allow-no-update). Required if --all not given.
• -l, --list — Don't update any packages, just list them. If PACKAGE is empty, act as if --all was specified.
• -f, --force — Update all packages, regardless of whether they need to be version-wise.
• -d, --downdate — Downdate packages to match the latest unyanked version from the registry.
• -i, --allow-no-update — Allow to fresh install packages passed as PACKAGE argument. This is useful, for example, in pairing with cargo-install-update-config(1). Off by default.
• -g, --git — Also update git-originating packages. Off by default, because it's expensive.
• -q, --quiet — Don't print status messages to stdout and pass down --quiet to cargo subprocesses.
• --locked — Enforce packages' embedded Cargo.lock files. This is equivalent to CARGO_INSTALL_OPTS=--locked (globally) and cargo-install-update-config(1) --enforce-lock (per package) except it doesn't disable cargo-binstall.
• TIME-based version filtering — Only consider versions published at least TIME ago.

TIME is a floating-point amount of seconds, optionally suffixed with one of the following cumulative multipliers:

s(econds)  1
m(inutes)  60
h(hours)   60
d(ays)     24
w(eeks)    7
y(ears)    365.25 / 7

If the registry doesn't provide the "pubtime" key for some versions and any TIME was specified, these versions will never be considered. (The crates.io registry provides publication times for all versions, even historical ones.)

• -j, --jobs JOBS; -j, --jobs default — Run at most JOBS jobs at once, forwarded as -j JOBS to cargo install.
  • "default" is as many CPUs as are installed on the system (same as cargo install).
  • If negative, as many CPUs as are installed on the system + JOBS (minimum of 1; same as cargo install).
  • When combined with -J, dedicate JOBS CPUs to each cargo install, and do not forward. This means that at most around R_JOBS/JOBS crates will be built in parallel, so that each one can get around JOBS CPUs at once.
• -J, --recursive-jobs, -JR_JOBS, --recursive-jobs R_JOBS — Build crates in parallel to fill R_JOBS CPUs.

By default (and with -j JOBS), each cargo install invocation runs serially, on as many CPUs as are installed on the system (on R_JOBS CPUs).

With -J (-J R_JOBS) (-J -R_JOBS), cargo install-update creates a make jobserver with as many job slots as CPUs are installed on the system (R_JOBS job slots) (as many job slots as CPUs are installed on the system minus R_JOBS but at least 1) and passes it to cargo installs via $CARGO_MAKEFLAGS/$MAKEFLAGS/$MFLAGS.

Building a crate consists of several build steps, which can be, with some restrictions, parallelised within a single crate build (like downloading sources or compiling different unrelated dependency crates) that all feed into a final long link step.

By default (with -j) cargo runs as many jobs at once as allocated, within a single crate.

With -J (-J R_JOBS), job slots are shared across all cargo install processes, and they will collude to run as many jobs at once as allocated, overall.

Notice how this means you may be building up to R_JOBS crates in parallel, which may induce significant filesystem and memory pressure. Use -j JOBS to reduce the crates-at-a-time figure to around R_JOBS/JOBS.

If an empty value is given, defaults to the amount of CPUs installed on the system.

• -s, --filter PACKAGE_FILTER... — Only consider packages matching all filters.

PACKAGE_FILTER is in the form "key=value" or "!key=value", where key is any of:

• "toolchain": the package must be configured to be compiled with the specified toolchain via cargo-install-update-config(1).
• "name": the package name must match the given glob ("package" — literal "package"; "*kage" — ends with "kage"; &c.)

• -r, --install-cargo CARGO_EXECUTABLE — Cargo executable to run for installations.

Must behave indistinguishably from the default cargo with regards to on-disk state ("$CARGO_DIR/.crates.toml" and installed executables) and the arguments it accepts.

Default: $CARGO, if set, otherwise "cargo"

• -c, --cargo-dir CARGO_DIR; --root CARGO_DIR — Set the directory containing cargo metadata.

Equivalent to, and forwarded as, cargo install --root.

Required. Default: "$CARGO_INSTALL_ROOT", then "$CARGO_HOME", then "$HOME/.cargo", otherwise manual.

• -t, --temp-dir TEMP_DIR — Set the directory in which to clone git repositories.

Adjoined with "cargo-update.$(id -un)" as last segment.

Required. Default: system temp, otherwise manual.

🌈 ENVIRONMENT VARIABLES 🌈

• $CARGO_REGISTRIES_CRATES_IO_PROTOCOL — Overrides the registries.crates-io.protocol Cargo configuration key.

The default is "sparse", and the crates.io URL is sparse+https://index.crates.io/. Set to some other value to use the git registry (https://github.com/rust-lang/crates.io-index) for crates.io.

• $CARGO_NET_GIT_FETCH_WITH_CLI — Overrides the net.git-fetch-with-cli Cargo configuration key.
• $GIT — Overrides the git executable in net.git-fetch-with-cli=true mode.
• $CARGO_HTTP_CAINFO — Overrides the http.cainfo Cargo configuration key.
• $CARGO_HTTP_CHECK_REVOKE — Overrides the http.check-revoke Cargo configuration key.
• $CARGO — cargo-install-update will run ${CARGO-cargo} install ..., unless overridden with -r.

Set automatically by cargo when running like "cargo install-update"

✨ EXAMPLES ✨

Okay bestie, this is the part where it all clicks. Real commands, real output, real vibes 💅

cargo install-update -a

Update all installed packages. That's it, that's the whole thing.

Example output:

      Polling registry 'https://index.crates.io/'........

  Package         Installed  Latest   Needs update
  checksums       v0.5.0     v0.5.2   Yes
  treesize        v0.2.0     v0.2.1   Yes
  cargo-count     v0.2.2     v0.2.2   No
  cargo-graph     v0.3.0     v0.3.0   No
  cargo-outdated  v0.2.0     v0.2.0   No
  identicon       v0.1.1     v0.1.1   No
  racer           v1.2.10    v1.2.10  No
  rustfmt         v0.6.2     v0.6.2   No

  Updating checksums
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Downloading checksums v0.5.2
     [...]
     Compiling checksums v0.5.2
      Finished release [optimized] target(s) in 95.2 secs
     Replacing D:\Users\nabijaczleweli\.cargo\bin\checksums.exe

  Updating treesize
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Downloading treesize v0.2.1
     [...]
     Compiling treesize v0.2.1
      Finished release [optimized] target(s) in 76.77 secs
     Replacing D:\Users\nabijaczleweli\.cargo\bin\treesize.exe

  Updated 2 packages.

See how it only actually touched the two that said Yes? Main character behavior — no wasted motion 🌿

---

cargo install-update racer treesize cargo-cln

Only consider racer, treesize and cargo-cln for updates. Since cargo-cln is not installed, it'll be ignored.

Lowkey the "ignored" part is doing a lot of work here — not every name you drop in exists, and that's fine 🫶

Example output:

      Updating registry `https://github.com/rust-lang/crates.io-index`

  Package   Installed  Latest   Needs update
  racer     v1.2.10    v1.2.10  No
  treesize  v0.2.0     v0.2.1   Yes

  Updating treesize
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Downloading treesize v0.2.1
     [...]
     Compiling treesize v0.2.1
      Finished release [optimized] target(s) in 76.77 secs
     Replacing D:\Users\nabijaczleweli\.cargo\bin\treesize.exe

  Updated 1 package.

Notice cargo-cln didn't even make it into the table. Ghosted. 👻

---

cargo install-update -al

List all installed packages, don't update any. Drama-free. A pure vibe check ✨

~/.cargo/bin/identicon.exe was removed manually, so a note is issued.

Heads up bestie — if you yeet an executable by hand, this is how the tool tells you about it. It's not mad, it's just disappointed 😭

Example output:

      Updating registry `https://github.com/rust-lang/crates.io-index`

  Package         Installed  Latest   Needs update
  checksums       v0.5.0     v0.5.2   Yes
  treesize        v0.2.0     v0.2.1   Yes
  cargo-count     v0.2.2     v0.2.2   No
  cargo-graph     v0.3.0     v0.3.0   No
  cargo-outdated  v0.2.0     v0.2.0   No
  identicon       v0.1.1     v0.1.1   No
  racer           v1.2.10    v1.2.10  No
  rustfmt         v0.6.2     v0.6.2   No

  identicon contains removed executables (identicon.exe), which will be re-installed on update ‒ you can remove it with cargo uninstall identicon

That last line is literally the whole plot twist — the note spells out exactly what happens on update and gives you the escape hatch 🚪

---

cargo install-update -af

Update all installed packages. Same energy as -a, except things get a little messy here, and honestly the output is showing you the messy on purpose 🍓

Example output:

      Updating registry `https://github.com/rust-lang/crates.io-index`

  Package       Installed  Latest   Needs update
  treesize      v0.2.0     v0.2.1   Yes
  clippy        v0.0.1     v0.0.99  Yes
  clippy_lints  v0.0.1     v0.0.99  Yes
  racer         v1.2.10    v1.2.10  No

  Updating racer
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Downloading racer v1.2.10
     [...]
     Compiling racer v1.2.10
      Finished release [optimized] target(s) in 51.43 secs
     Replacing D:\Users\nabijaczleweli\.cargo\bin\racer.exe

  Updating clippy
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Downloading clippy v0.0.99
     [...]
     Compiling clippy v0.0.99
     [...]
  error: failed to compile `clippy v0.0.99`, intermediate artifacts can be found at `T:\-_-TEM~1\cargo-install.WOcMlrKQ5Sok`

  Updating treesize
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Downloading treesize v0.2.1
     [...]
     Compiling treesize v0.2.1
      Finished release [optimized] target(s) in 76.77 secs
     Replacing D:\Users\nabijaczleweli\.cargo\bin\treesize.exe

  Updating clippy_lints
      Updating registry `https://github.com/rust-lang/crates.io-index`
  error: specified package has no binaries

  Updated 2 packages.
  Failed to update clippy, clippy_lints.

Two very different errors, zero panic — one package failed to compile, the other literally ships no binaries. Both get reported at the end, and the ones that did work still got updated. Resilient queen behavior 👑💀

---

cargo install-update -i checksums rustfmt treesize

Install specified packages, their installation status notwithstanding.

Read that again: notwithstanding. It installs them whether or not they're already installed. checksums isn't installed → gets Installing. treesize is installed and outdated → gets Replacing. 🎀

Example output:

      Updating registry `https://github.com/rust-lang/crates.io-index`

  Package    Installed  Latest   Needs update
  checksums             v0.5.2   Yes
  treesize   v0.2.0     v0.2.1   Yes
  rustfmt    v0.6.2     v0.6.2   No

  Installing checksums
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Downloading checksums v0.5.2
     [...]
     Compiling checksums v0.5.2
      Finished release [optimized] target(s) in 95.2 secs
     Installing D:\Users\nabijaczleweli\.cargo\bin\checksums.exe

  Updating treesize
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Downloading treesize v0.2.1
     [...]
     Compiling treesize v0.2.1
      Finished release [optimized] target(s) in 76.77 secs
     Replacing D:\Users\nabijaczleweli\.cargo\bin\treesize.exe

  Updated 2 packages.

Note the blank Installed cell for checksums — it's giving "not yet, but soon" 🌸

---

cargo install-update -i with (file:///usr/local/share/cargo):zram-generator:0.1.1

So the command is:

cargo install-update -i
(file:///usr/local/share/cargo):zram-generator:0.1.1

Install zram-generator from a local repository in /usr/local/share/cargo (but a remote one or a short name <span>will work just as well</span>), at most version 0.1.1.

Short name? Works. Remote repo? Works. Local path? Works. The tool does not gatekeep 🦋

Example output:

      Updating registry `file:///usr/local/share/cargo`

  Package         Installed  Latest   Needs update
  zram-generator             v0.1.1   Yes

  Installing zram-generator
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Downloading zram-generator v0.1.1
     [...]
     Compiling zram-generator v0.1.1
      Finished release [optimized] target(s) in 21.62 secs
    Installing /home/nabijaczleweli/.cargo/bin/zram-generator
     Installed package `zram-generator v0.1.1` (executable `zram-generator`)

  Updated 1 package.

Notice the registry it polls is your file:// one, then it pulls the actual crate from crates.io. Two different registries in one example, no cap 🌈

---

cargo install-update -ag

Update all installed packages, including ones from git.

Two tables in this one, bestie — registry packages first, then the git ones. Keep scrolling, it's worth it 💜

Example output:

      Updating registry `https://github.com/rust-lang/crates.io-index`

  Package         Installed  Latest   Needs update
  checksums       v0.5.0     v0.5.2   Yes
  cargo-count     v0.2.2     v0.2.2   No

  Updating checksums
      Updating registry `https://github.com/rust-lang/crates.io-index`
     Downloading checksums v0.5.2
     [...]
     Compiling checksums v0.5.2
      Finished release [optimized] target(s) in 95.2 secs
     Replacing D:\Users\nabijaczleweli\.cargo\bin\checksums.exe

  Updated 1 package.

  Package                Installed  Latest   Needs update
  alacritty              eb231b3    5f78857  Yes
  chattium-oxide-client  108a7b9    108a7b9  No

  Updating alacritty from https://github.com/jwilm/alacritty
      Updating git repository `https://github.com/jwilm/alacritty`
     Installing alacritty v0.1.0 (https://github.com/jwilm/alacritty#5f788574)
     [...]
     Compiling alacritty v0.1.0
      Finished release [optimized] target(s) in 127.6 secs
     Replacing D:\Users\nabijaczleweli\.cargo\bin\alacritty.exe

  Updated 1 package.

See the git versions? Those are commit hashes, not semver — eb231b3 → 5f78857. Commit-hash diffing is so real 🧚 And yes, it prints the URL it's updating from and the resolved #5f788574 in the install line 🎀

---

💖 AUTHOR 💖

Written by these absolute legends, all of them, in order, no cuts:

• наб <nabijaczleweli@nabijaczleweli.xyz>
• Yann Simon <yann.simon.fr@gmail.com>
• ven <vendethiel@hotmail.fr>
• Cat Plus Plus <piotrlegnica@piotrl.pl>
• Liigo <liigo@qq.com>
• azyobuzin <azyobuzin@users.sourceforge.jp>
• Tatsuyuki Ishi <ishitatsuyuki@gmail.com>
• Tom Prince <tom.prince@twistedmatrix.com>
• Mateusz Mikuła <mati865@gmail.com>
• sinkuu <sinkuupump@gmail.com>
• Alex Burka <aburka@seas.upenn.edu>
• Matthias Krüger <matthias.krueger@famsik.de>
• Daniel Holbert <dholbert@cs.stanford.edu>
• Jonas Bushart <jonas@bushart.org>
• Harrison Metzger <harrisonmetz@gmail.com>
• Benjamin Bannier <bbannier@gmail.com>
• Dimitris Apostolou <dimitris.apostolou@icloud.com>
• Corbin Uselton <corbinu@decimal.io>
• QuarticCat <QuarticCat@protonmail.com>
• Artur Sinila <freesoftware@logarithmus.dev>
• qthree <qthree3@gmail.com>
• tranzystorekk <tranzystorek.io@protonmail.com>
• Paul Barker <paul@pbarker.dev>
• Benoît Cortier
• Biswapriyo Nath <nathbappai@gmail.com>
• Shiraz <smcclennon@protonmail.com>
• Victor Song <vms2@rice.edu>
• chrisalcantara <chris@chrisalcantara.com>
• Utkarsh Gupta <utkarshgupta137@gmail.com>
• nevsal
• Rui Chen <https://chenrui.dev>
• Lynnesbian <https://fedi.lynnesbian.space/@lynnesbian>
• Rene Leonhardt
• Maxime Guerreiro <maxime@cloudflare.com>
• and Brian

That's a whole group chat and they all showed up. 🫶💜

---

🌟 SPECIAL THANKS 🌟

To all who support further development, in particular:

• ThePhD
• Embark Studios
• Lars Strojny
• EvModder

Sponsor-coded icons only, we love to see it 👑✨

---

🐛 REPORTING BUGS 🐛

Found something cursed? Take it here, don't suffer in silence:

<https://github.com/nabijaczleweli/cargo-update/issues>

Bestie pls include what you ran and what it said — receipts make fixes happen faster 📸

---

🦋 SEE ALSO 🦋

• <https://github.com/nabijaczleweli/cargo-update>
• <https://github.com/ryankurte/cargo-binstall>

---

Okay that's the whole page, you made it to the end 🎉 Go update something, you icon. 💅🌸

This one's brought to you by the cargo-update developers, dated all the way back in January 1980 (yes, really, that's the date on the tin, CARGO-INSTALL-UPDATE(1) 🎀).