Skip to content

install-linux.md

Latest commit

 

History

History
159 lines (106 loc) · 5.29 KB

install-linux.md

File metadata and controls

159 lines (106 loc) · 5.29 KB
Raw

Install Qube on Linux

Official Linux builds ship as AppImage, .deb (Ubuntu/Debian), .rpm (Fedora/RHEL), and .tar.gz (portable) in three inference variants:

Variant Best for Artifact examples
cpu Any PC; slowest inference Qube-1.1.0-x86_64-cpu.AppImage, qube_1.1.0_amd64.deb, qube-1.1.0-1.x86_64.rpm
vulkan AMD / Intel GPUs Qube-1.1.0-x86_64-vulkan.AppImage, qube-vulkan_1.1.0_amd64.deb, qube-vulkan-1.1.0-1.x86_64.rpm
cuda NVIDIA GPUs (recent driver) Qube-1.1.0-x86_64-cuda.AppImage, qube-cuda_1.1.0_amd64.deb, qube-cuda-1.1.0-1.x86_64.rpm

Install one packaged variant at a time (.deb / .rpm packages conflict with each other). AppImages and tarballs are portable — keep the file that matches your hardware.

Flatpak is not published today — use AppImage, .deb, .rpm, or .tar.gz from GitHub Releases.

For development or bleeding-edge checkouts, use install from source.

System requirements

  • Ubuntu 22.04+ / Debian 12+ (amd64) for .deb packages

  • Fedora 39+ / RHEL 9+ (x86_64) for .rpm packages (dependency names target Fedora/RHEL)

  • 16 GB RAM minimum (20 GB recommended)

  • Microphone and speakers for voice features

  • Vulkan builds: working Vulkan drivers/mesa stack (libvulkan1)

  • CUDA builds: proprietary NVIDIA driver compatible with CUDA 12.4 wheels (no separate CUDA toolkit required for the packaged app)

  • Runtime libraries (.deb installs these automatically; AppImage bundles most GUI libs):

    sudo apt install libportaudio2 libgl1 libxcb1 libxkbcommon0

See system requirements for model and storage guidance.

AppImage (recommended for first try)

  1. Download the AppImage for your GPU from GitHub Releases.

  2. Make it executable and run:

    chmod +x Qube-1.1.0-x86_64-vulkan.AppImage
./Qube-1.1.0-x86_64-vulkan.AppImage

  3. Optional — application menu entry (from the repo checkout, or after cloning the install script):

    bash scripts/linux/install_appimage.sh ./Qube-*-x86_64-vulkan.AppImage
qube-appimage

    This copies the AppImage to ~/.local/opt/qube/Qube.AppImage, adds ~/.local/bin/qube-appimage, and registers a .desktop launcher.

On systems without FUSE, set:

export APPIMAGE_EXTRACT_AND_RUN=1
./Qube-1.1.0-x86_64-vulkan.AppImage

User data is stored under ~/.qube/ (shared across variants).

Updating

To upgrade an existing install, see Update Qube. In short: run sudo apt install ./qube_<new>_amd64.deb for .deb, or re-run install_appimage.sh for AppImage menu integration.

Debian / Ubuntu (.deb)

  1. Download the matching .deb from GitHub Releases.

  2. Install one variant:

    sudo apt install ./qube_1.1.0_amd64.deb          # CPU
sudo apt install ./qube-vulkan_1.1.0_amd64.deb   # AMD/Intel (Vulkan)
sudo apt install ./qube-cuda_1.1.0_amd64.deb     # NVIDIA (CUDA)

  3. Launch from your application menu or run:

    qube

The package installs the PyInstaller bundle to /opt/qube/, a /usr/bin/qube wrapper, and /usr/bin/qube-uninstall for removal.

To switch variants later, remove the installed package first (qube-uninstall or sudo apt remove), then install the other .deb.

Fedora / RHEL (.rpm)

  1. Download the matching .rpm from GitHub Releases.

  2. Install one variant:

    sudo dnf install ./qube-1.1.0-1.x86_64.rpm          # CPU
sudo dnf install ./qube-vulkan-1.1.0-1.x86_64.rpm   # AMD/Intel (Vulkan)
sudo dnf install ./qube-cuda-1.1.0-1.x86_64.rpm      # NVIDIA (CUDA)

    On RHEL/CentOS with yum:

    sudo yum install ./qube-1.1.0-1.x86_64.rpm

  3. Launch from your application menu or run qube.

The RPM installs the same /opt/qube/ layout and /usr/bin/qube wrapper as the .deb. Package names conflict — install only one variant.

Portable tarball (.tar.gz)

  1. Download Qube-<version>-x86_64-{cpu,vulkan,cuda}.tar.gz from GitHub Releases.

  2. Extract and run:

    tar -xzf Qube-1.1.0-x86_64-vulkan.tar.gz
./Qube/Qube

No system integration (no menu entry or /usr/bin wrapper). User data still goes to ~/.qube/. Install runtime libraries manually if the bundle fails to start (see system requirements above).

Uninstall

See uninstall.md.

Build locally (maintainers)

bash scripts/linux/install_build_deps.sh vulkan   # or cpu / cuda / all
bash scripts/linux/build_linux.sh 9.9.9 vulkan
bash scripts/release/smoke_linux_dist.sh
bash scripts/linux/fetch_appimage_tools.sh
bash scripts/linux/build_appimage.sh 9.9.9 vulkan
bash scripts/linux/build_deb.sh 9.9.9 vulkan
bash scripts/linux/build_rpm.sh 9.9.9 vulkan
bash scripts/linux/build_tarball.sh 9.9.9 vulkan

Revert core/__version__.py and pyproject.toml after dry runs if needed.

Related