Installation

Installation

Flathub (Recommended)

The easiest way to install QBZ. All dependencies are bundled.

flatpak install flathub com.blitzfc.qbz

Then launch with:

flatpak run com.blitzfc.qbz

Or find "QBZ" in your application menu.

Snap Store

sudo snap install qbz-player

MPRIS media controls work in the Snap build (the Canonical auto-connect review cleared back in the 1.2.x series).

AUR (Arch Linux)

Using your preferred AUR helper:

yay -S qbz-bin

Or manually:

git clone https://aur.archlinux.org/qbz-bin.git
cd qbz-bin
makepkg -si

Gentoo

QBZ has its own overlay with both a prebuilt-binary ebuild (qbz-bin, recommended) and a from-source one (qbz):

sudo eselect repository add qbz-overlay git https://github.com/vicrodh/qbz-overlay.git
sudo emerge --sync qbz-overlay
sudo emerge media-sound/qbz-bin    # prebuilt binary (recommended)
# or, to build from source:
sudo emerge media-sound/qbz

Source-build warning (even by Gentoo standards): the qbz UI is one ~1.6M-line generated compilation unit that peaks around 20–30 GB of RAM and takes a long while, and every version bump recompiles it. qbz-bin spares you all of that.

NixOS / Nix

Two ways to install, in order of freshness:

1. Straight from the QBZ flake (always the current release). This is the authoritative Nix packaging — it tracks releases immediately.

# Run it once without installing
nix run github:vicrodh/qbz

To keep it, add the flake as an input in your system/home flake.nix and pull the qbz package from it:

{
  inputs.qbz.url = "github:vicrodh/qbz";
  # then, in your packages / environment.systemPackages:
  #   inputs.qbz.packages.${system}.default
}

2. From nixpkgs (qbz), if you prefer channel-managed packages:

nix profile install nixpkgs#qbz     # flakes
# or on classic channels:
nix-env -iA nixpkgs.qbz

The nixpkgs package can lag behind the latest release (it's updated by pull request after each version), so if you want the newest QBZ, use the flake above.

GitHub Releases

Download the latest release from the Releases page. Both x86_64 (amd64) and aarch64 (arm64) builds are published; the examples below use amd64 — swap amd64→aarch64 / x86_64→aarch64 for ARM.

Format	File	Instructions
Debian/Ubuntu	QBZ_x.y.z_amd64.deb	sudo apt install ./QBZ_*.deb (or sudo dpkg -i)
Fedora/RHEL	QBZ-x.y.z-1.x86_64.rpm	sudo dnf install ./QBZ-*.rpm (or sudo rpm -i)
AppImage	QBZ_x.y.z_amd64.AppImage	chmod +x QBZ_*.AppImage && ./QBZ_*.AppImage
Flatpak Bundle	qbz_x.y.z_x86_64.flatpak	flatpak install qbz_*.flatpak
Tarball	qbz_x.y.z_amd64.tar.gz	Extract and run ./qbz
Daemon (headless)	qbzd-x.y.z-linux-amd64.tar.gz	Extract and run ./qbzd — see Headless Daemon

Note: The .deb and .rpm packages already declare their dependencies, so a normal install pulls everything in. For the tarball or AppImage you may occasionally need a system library — see System Requirements.

APT Repository (Debian/Ubuntu)

For automatic updates via apt:

# Add the repository
echo "deb [trusted=yes] https://vicrodh.github.io/qbz-apt stable main" | sudo tee /etc/apt/sources.list.d/qbz.list

# Update and install
sudo apt update
sudo apt install qbz

Building from Source

Since 2.0, QBZ is a pure Rust + Slint project — no Node.js, npm or Tauri CLI.

Prerequisites

• Rust (stable, latest recommended)
• System dependencies listed in System Requirements

Build Steps

# Clone the repository
git clone https://github.com/vicrodh/qbz.git
cd qbz/crates

# Build the desktop app (release)
cargo build --release -p qbz

The compiled binary is at crates/target/release/qbz. To build the headless daemon instead, use -p qbzd.

Heads-up on RAM: the generated Slint UI crate (qbz_ui) is a single large compilation unit and a release build of it can peak at 20–30 GB of RAM. On a memory-constrained machine, lower the parallelism (CARGO_BUILD_JOBS=1) or use the helper script scripts/slint-run.sh, which auto-tiers the build to your available memory.

macOS (Experimental)

QBZ is a Linux-first application. macOS support is experimental and limited. Features like PipeWire, ALSA Direct, casting, and low-level device control are unavailable.

Download the unsigned DMG from Releases. Both Apple Silicon (aarch64) and Intel (x64) builds are published.

Since the DMG is unsigned, you need to allow it in System Settings > Privacy & Security after first launch.

macOS port maintained by @afonsojramos.

Headless Daemon (qbzd)

If you only want the windowless daemon on an always-on box (a Raspberry Pi, NUC, LXC container or headless server), grab the standalone qbzd-x.y.z-linux-<arch>.tar.gz from Releases, or use the qbzd binary that ships alongside qbz in the .deb / .rpm packages. Full setup, SSH login and service-file instructions live on the Headless Daemon page.

Verifying the Installation

After installing, launch QBZ and check the version in Settings > About (should read 2.0.2).

If you encounter issues, see Troubleshooting.