Installation

Installation

Flathub

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.

"QBZ is developed on Gentoo, by Gentoo lovers. Moo."

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

macOS is a supported platform (out of its experimental phase since 2.0), maintained by @afonsojramos. Apple Silicon is fully supported; Intel Macs are supported too, though older machines may feel slow by default (see below). PipeWire, ALSA Direct, casting and low-level device control are Linux-only; macOS plays through its own CoreAudio backend, with a Core Audio Direct passthrough path for bit-perfect output.

Download the DMG (Apple Silicon or Intel) from Releases and drag QBZ into Applications.

Getting past Gatekeeper (first launch is blocked)

QBZ is ad-hoc signed but not notarized (no Apple Developer subscription), so recent macOS (Sequoia / 15 and later) blocks the first launch, and the old right-click then Open trick no longer works for un-notarized apps. Remove the quarantine flag, pick one:

• Settings route: try to open QBZ once (it gets blocked), then go to System Settings > Privacy & Security, scroll to the "QBZ was blocked" message, and click Open Anyway.

• Terminal route (what the toggle does, without the clicking):

  xattr -dr com.apple.quarantine /Applications/QBZ.app

This is a one-time unlock for this copy of the app; updates installed through QBZ's own updater don't need it again.

Intel Macs: performance

Older Intel Macs can feel sluggish out of the box. In Settings > Appearance you can turn off the heavier effects (the dynamic album-art background and shader visualizers) and pick a lighter theme; that recovers most of the smoothness. See Composition and Themes and Visualization.

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.