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 PowerShell
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 rg BurntSushi/ripgrep

Install a specific asset kind:

upstream install rg BurntSushi/ripgrep -k binary

Preview an install without changing anything:

upstream install rg BurntSushi/ripgrep --dry-run

Search for repositories:

upstream search ripgrep

Inspect releases before installing:

upstream probe BurntSushi/ripgrep

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

Common Workflows

Install from a release source

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

Examples:

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

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

upstream install app owner/repo --match linux --exclude debug

Build from source

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

Examples:

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

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 rg
upstream package pin nvim
upstream package unpin nvim
upstream package rename nvim neovim

Import and export

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

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

Command Overview

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