This repository contains installer scripts and container configuration that make it simple to run QiDi Studio inside a lightweight Ubuntu 24.04 LTS container using Distrobox and Podman. The container approach protects you from library incompatibilities on rolling‑release distros such as CachyOS while still providing native GPU acceleration.
- Latest Release Resolution: Resolves the latest QiDi Studio Ubuntu 24 AppImage from the official GitHub releases by default, with overrides available via
--urlorQIDI_URL. - Hardware-Aware Detection: Automatically identifies Nvidia, AMD, or Intel GPUs and sets up the correct driver stack.
- Manual Hardware Override: Allows users to force a specific driver stack (Nvidia, AMD, Intel, or Generic) during setup.
- Image Source Selection: Choose between pulling a standard image from DockerHub or building a locally optimized image via specific
Containerfiles. - Automatic Resource Management (Auto‑Stop): The container shuts down (
distrobox stop) as soon as the QiDi Studio window is closed. - Desktop Integration: Clean integration into your application menu with corrected icon paths and categories.
- Robust Network Handling: Retries the installation with a DNS workaround if network resolution fails.
Ensure your host system has the following installed:
- Podman (Container Engine)
- Distrobox (Container Integration Tool)
- curl (for downloading releases)
- nvidia-container-toolkit and a generated CDI spec such as
/etc/cdi/nvidia.yaml(Only if you are using the Nvidia container path)
-
Clone the repository:
git clone https://github.com/AkitaEngineering/QiDi-Studio-CachyBox.git cd QiDi-Studio-CachyBox -
Run the default Bash installer:
Bash is the default and recommended install path:
chmod +x install.sh ./install.sh
If you specifically want the Fish variant instead:
chmod +x install.fish ./install.fish
-
Answer the interactive prompts.
The installer will:
- detect your GPU and let you override the driver stack (Nvidia/AMD/Intel/Generic),
- optionally build a custom container image or pull a prebuilt one,
- resolve the latest QiDi Studio Ubuntu 24 AppImage unless you override it,
- download that AppImage and register it with Distrobox.
Once complete the application will appear in your desktop menu; closing the window automatically stops the container.
Use these flags when you want to validate a host, automate installs, or preselect the installer prompts.
| Flag | Scope | Description |
|---|---|---|
--check |
Bash / Fish | Run prerequisite and environment checks, then exit without installing. |
--dry-run |
Bash / Fish | Print the actions the installer would take without changing the system. |
--non-interactive, --yes, -y |
Bash / Fish | Accept defaults and skip interactive prompts. |
--uninstall |
Bash / Fish | Hand off to the matching uninstaller while preserving the selected container name and dry-run/non-interactive mode. |
--url URL |
Bash / Fish | Use a specific AppImage instead of resolving the latest Ubuntu 24 release. |
--container-name NAME |
Bash / Fish | Override the default container name, qidi-studio. |
--gpu 1-4 |
Bash / Fish | Preselect the driver stack: 1 Nvidia, 2 AMD, 3 Intel, 4 Generic/software rendering. |
--image-source 1-2 |
Bash / Fish | Choose the image source up front: 1 pull the standard Ubuntu 24 image, 2 build the matching local containerfile.*. |
--log-file PATH |
Bash / Fish | Write installer logs to a custom path instead of the default log location. |
./install.sh --check
./install.sh --non-interactive --gpu 2 --image-source 2
./install.sh --dry-run --container-name qidi-studio-test./install.fish --non-interactive --url https://github.com/QIDITECH/QIDIStudio/releases/download/.../QIDIStudio.AppImageBash examples:
# AMD host: build the AMD-tuned local image
./install.sh --non-interactive --gpu 2 --image-source 2
# Intel host: build the Intel-tuned local image
./install.sh --non-interactive --gpu 3 --image-source 2
# Nvidia host: requires Podman CDI support
./install.sh --non-interactive --gpu 1 --image-source 2
# Preflight only: verify prerequisites and exit
./install.sh --check
# Dry run: preview the AMD install path without making changes
./install.sh --dry-run --non-interactive --gpu 2 --image-source 2Fish equivalents:
# AMD host: build the AMD-tuned local image
./install.fish --non-interactive --gpu 2 --image-source 2
# Intel host: build the Intel-tuned local image
./install.fish --non-interactive --gpu 3 --image-source 2
# Nvidia host: requires Podman CDI support
./install.fish --non-interactive --gpu 1 --image-source 2
# Preflight only: verify prerequisites and exit
./install.fish --check
# Dry run: preview the AMD install path without making changes
./install.fish --dry-run --non-interactive --gpu 2 --image-source 2The Nvidia example assumes nvidia-container-toolkit and a CDI spec such as /etc/cdi/nvidia.yaml; otherwise the installer falls back to Generic rendering in non-interactive mode.
| File | Purpose |
|---|---|
install.sh |
Default Bash installer for any Linux distro. |
install.fish |
Optional Fish-shell installer variant. |
uninstall.sh / uninstall.fish |
Clean up containers, images, and desktop entries. |
containerfile.amd, containerfile.intel, containerfile.nvidia |
Blueprints to build a local container image for AMD, Intel, or Nvidia hosts. |
docker-compose.yml |
Configuration for running QiDi Studio via podman compose or docker compose. |
- GPU override: Detects your GPU (e.g. AMD 7900XTX) but lets you pick a different stack if needed.
- Image source options: Use a prebuilt image or build one locally for maximum compatibility.
- Auto‑stop launcher: Exported desktop entry wraps the command so the container exits when the app closes.
- Icon fixup: Removes
/run/hostprefixes from exported.desktopfiles to avoid broken icons.
You can bypass the installer and run the container manually.
-
Export the desired image and Containerfile variables:
- Fish:
set -x QIDI_IMAGE qidi-custom-amd; set -x QIDI_CONTAINERFILE containerfile.amd - Bash:
export QIDI_IMAGE=qidi-custom-amd; export QIDI_CONTAINERFILE=containerfile.amd
- Fish:
-
Optional: override the AppImage URL if you need a specific release instead of the latest detected Ubuntu 24 build:
- Fish:
set -x QIDI_URL https://github.com/QIDITECH/QIDIStudio/releases/download/.../QIDIStudio.AppImage - Bash:
export QIDI_URL=https://github.com/QIDITECH/QIDIStudio/releases/download/.../QIDIStudio.AppImage
- Fish:
-
Launch:
podman compose up
On first launch, the compose setup builds the selected image if needed, resolves the latest Ubuntu 24 AppImage, and caches the extracted runtime under ~/.local/share/qidi-studio/. On later runs it only refreshes that cache when the resolved release URL changes.
- DNS errors: Installer retries with
--dns 1.1.1.1if it cannot resolve hosts. - Nvidia install hangs at container creation: Install
nvidia-container-toolkit, generate a CDI spec such assudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml, then rerun the installer. Without CDI support, the installer falls back to Generic rendering. - FUSE errors: The container installs
libfuse2*; make sure you have FUSE permissions. - Broken icons: Run
update-desktop-database ~/.local/share/applicationsafter install.
QiDi Studio depends on specific library versions that can conflict on rolling‑release distros. Distrobox provides a stable Ubuntu environment while still presenting the app as native.
No. The GPU is passed through directly via Mesa/DRI or the Nvidia stack, giving native performance in the 3D preview.
Configurations persist in ~/.config/QIDIStudio/ on the host. They remain intact if you reinstall or recreate the container.
To upgrade QiDi Studio or pick up changes from this repository, update this repo and rerun the installer with the same options you used originally.
git pull
./install.shThe installer removes any existing container with the selected name, recreates it, and resolves the latest Ubuntu 24 QiDi Studio AppImage by default. Your profiles and settings are normally preserved because they live in ~/.config/QIDIStudio/ on the host.
If you installed with specific flags before, reuse them during the upgrade. Examples:
# Generic / software rendering
./install.sh --non-interactive --gpu 4 --image-source 1
# Rebuild a custom local image during upgrade
./install.sh --non-interactive --gpu 2 --image-source 2
# Pin a specific upstream AppImage instead of the latest release
./install.sh --url https://github.com/QIDITECH/QIDIStudio/releases/download/.../QIDIStudio.AppImageFish users can follow the same process with ./install.fish and the same flags.
You only need to run the uninstaller first if you want a full clean reset. A normal upgrade does not remove your saved settings unless you explicitly choose that during uninstall.
Run ./uninstall.sh to remove the container, images, and desktop entries.
If you specifically want the Fish variant, run ./uninstall.fish.
You can also delegate to the matching uninstaller via ./install.sh --uninstall or ./install.fish --uninstall.
The code and configuration in this repository remain available under the MIT License.
This fork preserves attribution to the original MIT-licensed work by Sascha Schüller and includes Akita Engineering's QiDi Studio adaptations, fixes, and release work under the same repository license.
QIDI Studio itself is proprietary software owned by QIDITECH and is not redistributed under the MIT License in this repository.
See LICENSE.md for the full attribution wording and the proprietary-software disclaimer.
Original MIT-licensed work by Sascha Schüller. Adapted, fixed, and released for QiDi Studio by Akita Engineering.