cargo binstall
provides a low-complexity mechanism for installing rust binaries as an alternative to building from source (via cargo install
) or manually downloading packages. This is intended to work with existing CI artifacts and infrastructure, and with minimal overhead for package maintainers.
binstall
works by fetching the crate information from crates.io
, then searching the linked repository
for matching releases and artifacts, with fallbacks to quickinstall and finally cargo install
if these are not found.
To support binstall
maintainers must add configuration values to Cargo.toml
to allow the tool to locate the appropriate binary package for a given version and target. See SUPPORT.md for more detail.
You probably want to see this page as it was when the latest version was published for accurate documentation.
Here are the one-liners for installing pre-compiled cargo-binstall
binary from release on Linux and macOS:
curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
And the one-liner for installing a pre-compiled cargo-binstall
binary from release on Windows (x86_64 and aarch64):
Set-ExecutionPolicy Unrestricted -Scope Process; iex (iwr "https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.ps1").Content
To get started using cargo-binstall
first install the binary (either via cargo install cargo-binstall
or by downloading a pre-compiled release), then extract it using tar
or unzip
and move it into $HOME/.cargo/bin
.
We recommend using the pre-compiled ones because we optimize those more than a standard source build does.
We also provide pre-built artifacts with debuginfo for Linux and Mac.
These artifacts are suffixed with .full.tgz
on Linux and .full.zip
on Mac and Windows.
To upgrade cargo-binstall, use cargo binstall cargo-binstall
!
Supported packages can be installed using cargo binstall NAME
where NAME
is the crates.io package name.
Package versions and targets may be specified using the --version
and --target
arguments respectively, and will be installed into $HOME/.cargo/bin
by default. For additional options please see cargo binstall --help
.
[garry] โ ~ cargo binstall radio-sx128x --version 0.14.1-alpha.5
21:14:15 [INFO] Resolving package: 'radio-sx128x'
21:14:18 [INFO] This will install the following binaries:
21:14:18 [INFO] - sx128x-util (sx128x-util-x86_64-apple-darwin -> /Users/ryankurte/.cargo/bin/sx128x-util-v0.14.1-alpha.5)
21:14:18 [INFO] And create (or update) the following symlinks:
21:14:18 [INFO] - sx128x-util (/Users/ryankurte/.cargo/bin/sx128x-util-v0.14.1-alpha.5 -> /Users/ryankurte/.cargo/bin/sx128x-util)
21:14:18 [INFO] Do you wish to continue? yes/[no]
? yes
21:14:20 [INFO] Installing binaries...
21:14:21 [INFO] Done in 6.212736s
Nowadays, cargo-binstall
is smart enough. All you need just passing the crate name.
cargo binstall --no-confirm --no-symlinks cargo-edit cargo-watch cargo-tarpaulin \
watchexec-cli cargo-outdated just fnm broot stylua
If your favorite package fails to install, you can instead specify the pkg-url
, bin-dir
, and pkg-fmt
at the command line, with values as documented in SUPPORT.md.
For example:
$ cargo-binstall \
--pkg-url="{ repo }/releases/download/{ version }/{ name }-{ version }-{ target }.{ archive-format }" \
--pkg-fmt="txz" \
crate_name
The most ergonomic way to upgrade the installed crates is with cargo-update
. cargo-update
automatically uses cargo-binstall
to install the updates if cargo-binstall
is present.
Supported crates such as cargo-binstall
itself can also be updated with cargo-binstall
as in the example in Installation above.
- Why use this?
- Because
wget
-ing releases is frustrating,cargo install
takes a not inconsequential portion of forever on constrained devices, and often putting together actual packages is overkill.
- Because
- Why use the cargo manifest?
- Crates already have these, and they already contain a significant portion of the required information.
Also, there's this great and woefully underused (IMO)
[package.metadata]
field.
- Crates already have these, and they already contain a significant portion of the required information.
Also, there's this great and woefully underused (IMO)
- Is this secure?
- Yes and also no? We're not (yet? #1) doing anything to verify the CI binaries are produced by the right person/organization.
However, we're pulling data from crates.io and the cargo manifest, both of which are already trusted entities, and this is
functionally a replacement for
curl ... | bash
orwget
-ing the same files, so, things can be improved but it's also fairly moot
- Yes and also no? We're not (yet? #1) doing anything to verify the CI binaries are produced by the right person/organization.
However, we're pulling data from crates.io and the cargo manifest, both of which are already trusted entities, and this is
functionally a replacement for
- What do the error codes mean?
- You can find a full description of errors including exit codes here: https://docs.rs/binstalk/latest/binstalk/errors/enum.BinstallError.html
- Can I use it in CI?
- Yes! For GitHub Actions, we recommend the excellent taiki-e/install-action, which has explicit support for selected tools and uses
cargo-binstall
for everything else.
- Yes! For GitHub Actions, we recommend the excellent taiki-e/install-action, which has explicit support for selected tools and uses
- Are debug symbols available?
- Yes! Extra pre-built packages with a
.full
suffix are available and contain split debuginfo, documentation files, and extra binaries like thedetect-wasi
utility.
- Yes! Extra pre-built packages with a
If you have ideas/contributions or anything is not working the way you expect (in which case, please include an output with --log-level debug
) and feel free to open an issue or PR.