Upstream

Upstream is a rootless package manager for installing software directly from upstream release sources.

It fetches binaries, archives, AppImages, and other release artifacts from GitHub, GitLab, Gitea, direct URLs, and download pages. When nobody published a usable binary, it can build the project from source.

What it does

Installs software without root
Finds the right release asset for your OS and architecture
Installs from GitHub, GitLab, Gitea, URLs, and scraped download pages
Upgrades, reinstalls, removes, and rolls back packages
Builds Rust, .NET, Go, Zig, and CMake projects from source
Tracks stable, preview, and nightly release channels
Creates desktop entries for graphical applications
Verifies downloads with checksums and signatures when available
Imports and exports package lists, profiles, configuration, and trusted keys
Keeps shell hooks, cached documentation, and diagnostics in one place

Installation

There are a couple of ways to install Upstream.

Binary installers

Linux

curl -fsSL https://raw.githubusercontent.com/what386/upstream-rs/main/scripts/install/install.bash | bash

macOS

curl -fsSL https://raw.githubusercontent.com/what386/upstream-rs/main/scripts/install/install.zsh | zsh

Windows

iwr -useb https://raw.githubusercontent.com/what386/upstream-rs/main/scripts/install/install.ps1 | iex

Windows also requires the latest supported Microsoft Visual C++ v14 Redistributable. Install the package matching your architecture from Microsoft before running the installer.

Linux is the primary supported platform. Windows and macOS support are experimental. Windows is currently more supported and tested than macOS (which is to say not at all) MacOS is also missing some features, including desktop-entry creation.

Cargo

cargo install upstream-rs

Cargo installs work normally, but they cannot update themselves with upstream upgrade.

Manual installation

Download a release from the latest GitHub release, then make the binary executable (on Unix systems):

chmod +x upstream

Examples

Initialize shell integration:

upstream hooks init

Install something:

upstream install BurntSushi/ripgrep

Preview the install first:

upstream install BurntSushi/ripgrep --dry-run

Find software interactively:

upstream find ripgrep

Choose a release asset interactively:

upstream probe BurntSushi/ripgrep

Upgrade everything, or check without changing anything:

upstream upgrade
upstream upgrade --check

List, inspect, remove, and diagnose:

upstream list
upstream info ripgrep
upstream remove ripgrep
upstream doctor

Common workflows

Install a release

upstream install sharkdp/fd
upstream install neovim/neovim --tag v0.11.0
upstream install owner/repo --desktop
upstream install owner/repo --match-pattern linux --exclude-pattern debug

Packages are identified by their provider and repository slug. Upstream discovers executable aliases from the installed artifact, so a project does not need to use the same name for its repository and its binary.

Build from source

upstream build BurntSushi/ripgrep
upstream build owner/repo --branch main
upstream build owner/repo --build-profile dotnet

Supported build profiles are rust, dotnet, go, zig, and cmake. Build workspaces are cached under .upstream/cache/build/ when the project build system allows rebuilds to reuse its output.

Manage packages

upstream upgrade nvim ripgrep
upstream reinstall ripgrep
upstream package pin nvim
upstream package rename nvim neovim
upstream package set nvim match_pattern=linux,x86_64 trust_mode=checksum
upstream cache list
upstream cache clean docs

Import and export

upstream export config ./config.toml
upstream import config ./config.toml
upstream export packages ./packages.json
upstream import packages ./packages.json --latest
upstream export profile ./profile.json
upstream import profile ./profile.json --latest
upstream export keys ./keys.json
upstream import keys ./keys.json

Exports contain reinstallable references and metadata. They do not contain installed files or cache contents.

API tokens

Provider tokens are optional. They help avoid anonymous rate limits, but are required for private repositories.

upstream auth set github.api_token=github_pat_xxx
upstream auth list
upstream doctor

For GitHub, create a token under Settings > Developer settings > Personal access tokens. Tokens are stored separately in auth.toml and are not included in configuration or profile exports.

Documentation

Developer documentation is in docs/:

FAQ

Why not just use my distribution's package manager?

You should use it when it has the package and version you want. Upstream is for the gaps: small projects, portable binaries, newer versions, private repositories, or projects that are expected to be built from source.

Why Rust?

Because it's 🚀🚀🚀 BLAZINGLY FAST 🚀🚀🚀 and 💾💾💾 MEMORY SAFE 💾💾💾 and 🔒🔒🔒 ZERO-COST ABSTRACTIONS 🔒🔒🔒 and ⚡⚡⚡ FEARLESSLY CONCURRENT ⚡⚡⚡ an

License

MIT OR Apache-2.0

upstream-rs 2.20.3