Upstream

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

It installs binaries, archives, AppImages, and other release artifacts from sources like GitHub, GitLab, Gitea, direct URLs, and scraped download pages. It can also build from source when prebuilt artifacts are unavailable.

Features

• Install packages without root
• Automatically select assets for your OS and architecture
• Upgrade, remove, reinstall, and roll back packages
• Build from source using Rust, .NET, Go, Zig, or CMake
• Track stable, preview, or nightly channels
• Pin packages to prevent upgrades
• Create desktop entries for GUI apps
• Import/export package manifests and full snapshots
• Optional checksum and signature verification
• Shell integration hooks and diagnostics

Installation

Recommended

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

Cargo

cargo install upstream-rs

Cargo installs do not support upstream upgrade self-updates.

Manual

Download a release from:

https://github.com/what386/upstream-rs/releases/latest

Then make it executable:

chmod +x upstream

Quick Start

Initialize shell integration:

upstream hooks init

Install a package:

upstream install BurntSushi/ripgrep rg

Install a specific asset kind:

upstream install BurntSushi/ripgrep rg -k binary

Preview an install without changing anything:

upstream install BurntSushi/ripgrep rg --dry-run

Search for repositories:

upstream search ripgrep --language Rust

Search interactively and install a selected result:

upstream find ripgrep

find prompts for the package name after selection and defaults to the selected repository name.

Probe releases, choose an asset, and install it:

upstream probe BurntSushi/ripgrep

Inspect parsed releases without installing:

upstream probe BurntSushi/ripgrep --dry-run
upstream probe BurntSushi/ripgrep --json

Upgrade installed packages:

upstream upgrade

Check for available updates:

upstream upgrade --check

List installed packages:

upstream list

Remove a package:

upstream remove rg

Run diagnostics:

upstream doctor

API Tokens

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

Set a GitHub token with:

upstream config set github.api_token=github_pat_xxx

For GitHub, open your profile menu, then go to Settings > Developer settings > Personal access tokens.

Both of these will work: A fine-grained personal access token with public repository access. A classic personal access token with read:project permissions.

Run upstream doctor after configuring tokens to verify that they work.

Common Workflows

Install from a release source

upstream install <repo-or-url> <name>

The canonical form is <repo-or-url> <name>. For git repositories, upstream can fall back to the repository name when <name> is omitted. Direct URLs and scraped download pages may still require <name>.

Examples:

upstream install sharkdp/fd fd
upstream install BurntSushi/ripgrep
upstream install neovim/neovim nvim --tag v0.11.0
upstream install owner/repo app --desktop

Use --match and --exclude to guide asset selection:

upstream install owner/repo app --match linux --exclude debug
upstream install owner/repo app --match linux,x86_64 --exclude debug,symbols

Build from source

upstream build <repo-or-url> <name>

The canonical form is <repo-or-url> <name>. For git repositories, upstream can fall back to the repository name when <name> is omitted.

Examples:

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

Git source builds use cached workspaces under .upstream/cache/build/ so rebuilds and upgrades can reuse build output when the project build system supports it.

Supported build profiles:

rust
dotnet
go
zig
cmake

Upgrade packages

upstream upgrade
upstream upgrade nvim rg
upstream upgrade --check
upstream upgrade --check --machine-readable

Manage packages

upstream remove rg
upstream reinstall rg
upstream rollback restore
upstream rollback restore rg
upstream rollback list
upstream package pin nvim
upstream package unpin nvim
upstream package rename nvim neovim

rollback restore without package names restores the latest reversible transaction. After upgrading across breaking local data changes, run upstream migrate when release notes or doctor recommend it.

Import and export

upstream export ./packages.json
upstream import ./packages.json

upstream export ./backup.tar.gz --full
upstream import ./backup.tar.gz

Command Overview

Command	Purpose
install	Install from a release source
build	Build and install from source
upgrade	Upgrade packages
remove	Remove packages
reinstall	Reinstall using stored metadata
rollback	Manage rollback artifacts
list	Show installed packages
changelog	Show upstream release notes
docs	Search package documentation
search	Search provider repositories
find	Pick and install a search result
probe	Pick and install a release asset
config	Manage configuration
package	Pin, unpin, or rename packages
hooks	Manage shell integration
import	Import keys, manifests, or snapshots
export	Export manifests or snapshots
doctor	Check installation health

Use -y or --yes to accept confirmation prompts automatically.

Documentation

Detailed documentation is available in docs/:

• Documentation index
• Installation and paths
• Command reference
• Package lifecycle
• Building from source
• Configuration
• Trust and verification
• Backup, import, and export
• Troubleshooting

Notes

Upstream installs packages in user space and does not manage dependencies.

License

MIT OR Apache-2.0