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

Known limitation: MPRIS media controls are currently unavailable in the Snap build. The required auto-connect review from Canonical has been pending. If you have a Snapcraft forum account, please support the permission request. All other installation methods have full MPRIS support.

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

An ebuild is published in the project's overlay (both a binary qbz-bin and a from-source qbz ebuild are provided). Add the overlay and emerge qbz.

Nix / nixpkgs

QBZ ships a flake.nix, and a package is maintained for nixpkgs.

# Try it straight from the flake
nix run github:vicrodh/qbz

# Or, once merged into your channel
nix-env -iA nixpkgs.qbz   # attribute name may vary by channel

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.