Install

Install script, Homebrew, Nix, cargo binstall, release archives, or build from source.

QQ is a single static binary. Pick one route; every route ends with the same qq on your PATH.

Install script (Linux, macOS)

curl -fsSL https://retsu-ai.github.io/qq/install.sh | sh

The same script is in the repository as install.sh; the site serves the copy from the latest main. The script detects your OS and CPU, downloads the matching archive from the latest GitHub release, verifies it against that release’s SHA256SUMS, and installs qq into ~/.local/bin. It never uses sudo; if the directory is not on your PATH, it prints the line to add. It supports Linux x86_64 and aarch64 (static musl, any distribution) and macOS Intel and Apple silicon, and refuses anything else with a pointer to the releases page.

Pin a version or change the directory with flags or environment variables:

curl -fsSL https://retsu-ai.github.io/qq/install.sh | sh -s -- --version 0.1.6 --dir /opt/qq/bin
QQ_VERSION=0.1.6 QQ_INSTALL_DIR="$HOME/bin" sh install.sh

sh install.sh --help lists the options. To upgrade, run it again.

Homebrew (macOS, Linux)

brew install retsu-ai/qq/qq

The formula in the retsu-AI/homebrew-qq tap is generated by the release workflow from each release’s SHA256SUMS, so it always points at the archives above. Homebrew does not pin versions of tap formulae; pin with install.sh --version instead.

Nix

nix run github:retsu-AI/qq -- --version    # run without installing
nix profile install github:retsu-AI/qq     # install into your profile

The flake exposes packages.qq (also packages.default) built from source with the pinned toolchain, and apps.default runs it. Pin a release with a ref: nix run github:retsu-AI/qq/v0.1.6. nix build .#qq inside a clone builds the same package; nix develop gives a shell with the exact toolchain.

cargo-binstall

cargo binstall --git https://github.com/retsu-AI/qq qq

cargo-binstall reads the [package.metadata.binstall] table in Cargo.toml and downloads the release archive for your target instead of compiling. Pass --version 0.1.6 to pin. The --git form is required because the crate is not published on crates.io; a plain cargo binstall qq would resolve a different crate of the same name.

From source

Requires the pinned stable Rust toolchain (rust-toolchain.toml selects it automatically inside the repository):

cargo install --git https://github.com/retsu-AI/qq --locked qq            # latest main
cargo install --git https://github.com/retsu-AI/qq --tag v0.1.6 --locked qq

or from a clone: cargo build --release and install target/release/qq. cargo build --release --no-default-features builds the minimal profile without the Amazon Bedrock family and its AWS SDK dependency closure; use it when you only need the HTTP providers.

Windows

Download qq-vX.Y.Z-x86_64-pc-windows-msvc.zip and SHA256SUMS from the latest release, check the hash with Get-FileHash, extract qq.exe, and put its folder on Path. cargo binstall --git https://github.com/retsu-AI/qq qq also works on Windows and does the download and check for you.

Verifying downloads

Every release attaches one archive per target and a SHA256SUMS file covering all of them:

Target	Archive
Linux x86_64 (static musl)	`qq-vX.Y.Z-x86_64-unknown-linux-musl.tar.gz`
Linux aarch64 (static musl)	`qq-vX.Y.Z-aarch64-unknown-linux-musl.tar.gz`
macOS Apple silicon	`qq-vX.Y.Z-aarch64-apple-darwin.tar.gz`
macOS Intel	`qq-vX.Y.Z-x86_64-apple-darwin.tar.gz`
Windows x86_64	`qq-vX.Y.Z-x86_64-pc-windows-msvc.zip`

install.sh, Homebrew, and cargo-binstall verify the archive against these sums before installing; a mismatch installs nothing. To verify by hand:

V=0.1.6 T=x86_64-unknown-linux-musl
curl -fsSLO "https://github.com/retsu-AI/qq/releases/download/v$V/qq-v$V-$T.tar.gz"
curl -fsSLO "https://github.com/retsu-AI/qq/releases/download/v$V/SHA256SUMS"
sha256sum --ignore-missing -c SHA256SUMS      # macOS: shasum -a 256 --ignore-missing -c SHA256SUMS
tar -xzf "qq-v$V-$T.tar.gz" && install -m 755 "qq-v$V-$T/qq" ~/.local/bin/qq

macOS may quarantine a binary downloaded by a browser. If qq is blocked, run xattr -d com.apple.quarantine qq once; curl-based routes are not affected.

Check the install

qq --version        # qq 0.1.6 (fef41a4 2026-10-08)
qq version          # adds the protocol, capabilities, descriptor, and store schema versions
qq config paths     # where QQ will look for configuration and keep sessions

Upgrade

Rerun the route you installed with (install.sh, brew upgrade qq, nix profile upgrade, cargo binstall --git … qq). QQ uses 0ver: a patch release can change compatibility contracts. Read the release’s Upgrading notes before upgrading. Locate the session store in the data directory printed by qq config paths. For a safe backup, stop every QQ process (qq serve, the TUI, and any qq run) and copy sessions.sqlite3 together with any adjacent sessions.sqlite3-wal and sessions.sqlite3-shm files. If QQ must stay running, use SQLite’s consistent .backup instead; do not copy a live database or data directory non-atomically. Follow the absolute-path backup and rollback procedure in the release’s Upgrading notes on the releases page. Upgrade/restart server and clients together when the protocol changes. qq version shows the store schema QQ migrates to on first open; migrations are forward-only, so rollback needs the old binary and a pre-upgrade backup.

Uninstall

Remove the binary (rm ~/.local/bin/qq, brew uninstall qq, nix profile remove, or cargo uninstall qq), then optionally:

Remove	Path (`qq config paths` prints yours)
configuration	the `global:` directory
sessions and trust state	the `data:` directory
credentials	`qq auth list`, then `qq auth logout <name>` for each

Next: Quickstart.