ubi: one command to install a prebuilt binary from a GitHub or GitLab release

Four words in the title, each one narrowing the scope

The project defines itself with a short paragraph that is worth reading closely, because the name is deliberately overloaded and the author takes the trouble to disambiguate all four parts.

Universal means it downloads binaries from GitHub or GitLab releases. Binary means it handles single-file executables, the kind created by most Go and Rust projects. Installer means it plops the binary wherever you tell it to. And UBI does not mean universal basic income, though that would be nice too.

Those three definitions together exclude most of what a package manager does. There is no dependency resolution, no version pinning per project, no lockfile, no manifest. There is one binary and one directory.

The scope is stated again in the section that asks whether you should use the tool at all, and the answer is more careful than you would expect from a project with a one-line install. If you want per-project tooling, the author strongly recommends mise instead of ubi. If you just want a simple tool for globally installing things like ripgrep or go-grip, then ubi is a good choice.

So the honest position is that this is a deliberately small tool with a clearly drawn boundary, and the author tells you where the boundary is before you install anything. The primary language is Rust, the licence is Apache-2.0, and the repository has a Cargo workspace with two members, the ubi library and the ubi-cli binary.

Installing ubi itself with a piped shell script

The CLI is distributed as a release binary, and the quick path is the bootstrap script rather than a package manager.

On Linux, macOS, FreeBSD and NetBSD:

curl --silent --location \
    https://raw.githubusercontent.com/houseabsolute/ubi/master/bootstrap/bootstrap-ubi.sh |
    sh

The script picks its destination based on who is running it. As a non-root user it installs into $HOME/bin, and as root it installs into /usr/local/bin. You can also download the latest release asset by hand from the releases page if you would rather not pipe a script into a shell.

The script accepts several environment variables as parameters, and they are worth knowing before you hit a problem with it. TARGET is the directory to install into, defaulting to $HOME/bin for non-root users and /usr/local/bin for root. TAG is the ubi version tag to download, defaulting to the latest release. FILENAME is the name of the release file asset to download, and using it skips platform detection entirely, which the documentation recommends if the script fails to detect your platform, while asking you to submit a pull request to fix the detection. GITHUB_TOKEN is the API token to use when downloading releases, and it is only necessary for private repositories or when you are hitting the anonymous GitHub API usage limits, which the documentation notes is most likely to happen when running the bootstrap script repeatedly in CI.

The variables can be set in the environment or on the command line, with one important detail: you have to set them on the right side of the pipe. To install a specific version:

curl --silent --location \
    https://raw.githubusercontent.com/houseabsolute/ubi/master/bootstrap/bootstrap-ubi.sh |
    TAG=v0.0.15 sh

There is a caveat for GitHub Enterprise users. If you run the script from an Action inside a GitHub Enterprise installation, the GITHUB_TOKEN in that environment belongs to the Enterprise setup, and you need to create a separate token for github.com and pass it explicitly as GITHUB_TOKEN.

Windows is handled by a PowerShell bootstrap that installs ubi.exe into the current directory, which you can run from a command or from the PowerShell command line.

The library and the CLI are separate crates in one workspace

The project ships in two forms, and the split is in the Cargo workspace members: ubi and ubi-cli.

As a library, adding it to a Cargo project is a single dependency line:

[dependencies]
ubi = "x.y.z"

The API documentation is published on docs.rs. The workspace Cargo.toml declares the package metadata: edition 2021, the licence as MIT OR Apache-2.0, version 0.12.0, and the author as Dave Rolsky. The repository is the houseabsolute/ubi repository, and the workspace uses the version 2 resolver.

The CLI is a thin layer over that library. The flag table in the documentation gives the shape of the interface, and it is a straightforward one. The project to install is given with -p or --project, or the environment variable UBI_PROJECT, and it is not allowed together with --url. The example values are a short owner and repository pair like houseabsolute/precious, or the full GitHub URL. The tag to download is given with -t or --tag, or UBI_TAG, and it defaults to the latest release, and it is only valid when --project is also passed.

So the essential invocation is a project and, optionally, a tag. Everything else in the tool is about how it resolves that pair into a file: which asset matches your platform, how the archive is unpacked, and where the executable is placed.

The dependency list in the workspace explains a good deal about the implementation. There is reqwest for HTTP, and it is configured with gzip and json, and the configuration carries a long comment about why the rustls feature used is rustls-no-provider rather than rustls: the aws-lc-rs crypto provider that the rustls feature pulls in needs a C and C++ toolchain and fails to build under cross for targets such as NetBSD and PowerPC64, so the project installs the ring provider itself and points at ubi::builder::install_crypto_provider. There is flate2 and bzip2 for decompression, binstall-tar for archive extraction, the platforms crate for OS and architecture detection, serde and chrono for the metadata, itertools and lazy-regex for the parsing work, and rstest and mockito for testing, which is a hint about how the release-asset matching is tested.

The cross-compilation setup and the release machinery in the repository

The repository is organised like a well-run Rust project, and the tree tells you about the parts that are not user facing.

There is a Cross.toml for cross-compilation, and the comment in the Cargo.toml about aws-lc-rs failing under cross for NetBSD and PowerPC64 explains why that matters here: this is a tool that has to build for a wide range of targets, because a binary installer is only useful if it runs on the platform it is meant to install binaries for.

The build is driven by a Justfile rather than a Makefile, and there is also a mise.toml for the tool's own development environment setup, which is a nice touch given that the author recommends mise to users for per-project tooling. The formatting and linting are configured in rustfmt.toml, clippy.toml and .oxfmtrc.json, with .typos.toml handling spelling checks. A precious.toml file holds the precious task definitions, and CODE_OF_CONDUCT.md, CONTRIBUTING.md, GOVERNANCE.md, SECURITY.md and SUPPORT.md are all present, which is the standard set of community health files for a project that wants outside contributions.

The release machinery is in release.toml, which is the release-plz configuration for automating version bumps and changelog entries, and Changes.md is the resulting changelog. The version history is quick to read: v0.9.0 on 2026-01-11, v0.10.0 on 2026-07-26 and v0.12.0 on 2026-08-31, with the last push to the repository on 2026-10-20. The version line is still below 1.0 and the cadence is irregular, which is worth remembering before you script around it.

The bootstrap/ directory holds the install scripts for the Unix shells and for PowerShell, docs/ holds the generated documentation, and the git/ directory holds the git-related integration.

Where ubi is the wrong tool

The first limit is the one the project names itself. If you want per-project tooling, with a version pinned in the repository and a different version per directory, ubi does not do that and the author tells you to use mise instead. Installing a tool globally and then discovering that another project on the same machine needs a different version is the failure mode the recommendation is aimed at.

The second limit is the single-file assumption. The whole model is that the release publishes one executable file. A tool distributed as a tarball with shared libraries, or as a directory of scripts, or as an application bundle, is out of scope. That is fine for the Go and Rust single-binary tools the author names, and it is not fine for a lot of other software.

The third is the platform detection. The documentation is candid that if the script fails to detect your platform you should set FILENAME and skip detection, and it asks you to submit a pull request to fix the detection. So an unsupported or unusual target, a musl libc system or an unusual architecture combination, will need the manual path, and the fix depends on somebody else accepting the pull request.

The fourth is the CI rate limit. The bootstrap script without a token will hit the anonymous GitHub API limits, and the documentation says this is most likely when running the script repeatedly in CI. In a CI pipeline the token is not optional, and the GITHUB_TOKEN in a GitHub Enterprise Action is not the token you need, so that environment needs a second token created for github.com specifically.

The fifth is that a shell script piped into sh is the install path. For a team with supply chain policies, that is a decision to make deliberately rather than by convenience, and the manual release-asset download is the alternative the documentation offers. There is also no package manager entry for ubi in the tree, so a workstation fleet that manages tools through a package manager has nothing to hook into.

Editorial conclusion

ubi is worth installing for someone who wants to put a handful of prebuilt tools on their PATH and nothing more, because it handles the release-asset naming conventions and platform detection for you and it is a single static binary you can fetch with one curl, and because it is also a library if your own tool needs to install other tools. It is the wrong tool for per-project tooling, and the project says so itself. Before you adopt it, check the three things the documentation tells you: that you have moved past the per-project case, since the author recommends mise instead and describes ubi as the simple global alternative; that your tools publish single-file release assets, since the whole model assumes the executable is one downloadable file; and that you are comfortable with a bootstrap script that pipes a shell script into sh, because the environment variables the script accepts, TARGET, TAG, FILENAME and GITHUB_TOKEN, are the only knobs available before the tool is even installed.

Frequently asked questions

Official sources

1. houseabsolute/ubi on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases