https://github.com/tchung1970/sd-cli-cuda
CUDA-accelerated Stable Diffusion plugin for wavespeed-desktop
https://github.com/tchung1970/sd-cli-cuda
cuda gpu linux nvidia stable-diffusion
Last synced: about 1 month ago
JSON representation
CUDA-accelerated Stable Diffusion plugin for wavespeed-desktop
- Host: GitHub
- URL: https://github.com/tchung1970/sd-cli-cuda
- Owner: tchung1970
- Created: 2025-12-27T19:44:12.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-28T17:30:15.000Z (6 months ago)
- Last Synced: 2025-12-29T19:13:07.842Z (6 months ago)
- Topics: cuda, gpu, linux, nvidia, stable-diffusion
- Language: Shell
- Size: 36.5 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# sd-cli-cuda
CUDA-accelerated Stable Diffusion plugin for [wavespeed-desktop](https://github.com/WaveSpeedAI/wavespeed-desktop).
## Overview
This is a **modular plugin** designed to add CUDA GPU acceleration to wavespeed-desktop on any Linux system with an NVIDIA GPU such as RTX 4000 Ada Generation.
The package provides [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp) compiled with CUDA support, enabling high-performance local image generation through wavespeed-desktop with Z-Image for local image generation.
### How It Works
1. **Standalone binary**: Installs `sd-cli` to `/usr/bin/`
2. **Auto-integration**: Creates symlink at `~/.config/wavespeed-desktop/sd-bin/sd` for wavespeed-desktop to detect
3. **Modular design**: wavespeed-desktop automatically uses the CUDA backend when available
### Build Process
The build script:
1. Clones the latest stable-diffusion.cpp source
2. Compiles with CUDA GPU acceleration
3. Packages into a `.deb` file for easy installation on Debian/Ubuntu systems
## Prerequisites
### System Requirements
- Debian/Ubuntu-based Linux distribution such as Ubuntu 24.04 LTS
- NVIDIA GPU with CUDA support such as RTX 4000 Ada Generation
### Build Dependencies
```bash
sudo apt update
sudo apt install -y \
build-essential \
cmake \
git \
nvidia-cuda-toolkit \
dpkg-dev
```
### Runtime Dependencies
- `libc6`
- `libstdc++6`
- `libgomp1`
- `libcudart12` - CUDA runtime library
- `libcublas12` - CUDA BLAS library
- `libcublaslt12` - CUDA BLAS LT library
- NVIDIA drivers (with CUDA support)
- `zenity` - VRAM error popup dialog (pre-installed on Ubuntu 24.04 GNOME)
- `xdotool` - popup window centering (auto-installed by postinst if missing)
CUDA libraries are automatically installed when using `apt install ./sd-cli-cuda_*.deb`.
## Building
```bash
./build.sh
```
The script will:
1. Clone stable-diffusion.cpp to `./src/` (shallow clone)
2. Build with CUDA enabled using all available CPU cores
3. Create `sd-cli-cuda_amd64.deb` in the repo root
Build time: ~3-5 minutes depending on hardware.
## Installation
```bash
# Recommended: auto-installs CUDA dependencies
sudo apt install ./sd-cli-cuda_1.0.2_amd64.deb
# Or manually (requires CUDA libs already installed)
sudo dpkg -i sd-cli-cuda_1.0.2_amd64.deb
```
### What Gets Installed
| Path | Description |
|------|-------------|
| `/usr/bin/sd-cli` | Command-line image generation tool |
| `~/.config/wavespeed-desktop/sd-bin/sd` | Symlink to sd-cli (for wavespeed-desktop integration) |
After installation, wavespeed-desktop will automatically detect and use the CUDA backend for GPU-accelerated image generation.
## Uninstallation
```bash
sudo dpkg -r sd-cli-cuda
```
## Usage
### With wavespeed-desktop (Recommended)
Simply install the package - wavespeed-desktop will automatically detect and use the CUDA backend. No additional configuration required.
### sd-cli (Standalone Command Line)
See [example.txt](example.txt) for a complete command-line example using wavespeed-desktop model paths.
Sample output (generated on NVIDIA RTX 4000 Ada Generation):
## Package Details
| Field | Value |
|-------|-------|
| Package Name | sd-cli-cuda |
| Version | 1.0.2 |
| Architecture | amd64 |
| License | MIT (upstream) |
| Source | https://github.com/leejet/stable-diffusion.cpp |
## Troubleshooting
### CUDA not found during build
Ensure CUDA toolkit is installed:
```bash
nvcc --version
```
### GPU not detected at runtime
Check NVIDIA driver:
```bash
nvidia-smi
```
### Out of VRAM
sd-cli checks GPU memory before running and requires 8GB free. When VRAM is insufficient:
1. wavespeed-desktop shows `CUDA Out of Memory!` in the error banner
2. A popup dialog appears with full details:
- Free/total VRAM in GB
- List of GPU processes consuming VRAM (PID, name, usage)
- Command to free VRAM
To free VRAM, close GPU-intensive applications:
```bash
sudo pkill -f 'main.py' # ComfyUI
```
## Related Projects
- [wavespeed-desktop](https://github.com/WaveSpeedAI/wavespeed-desktop) - Desktop application for local AI image generation
- [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp) - Upstream C++ implementation
## License
sd-cli-cuda is licensed under MIT License.
stable-diffusion.cpp is licensed under MIT License.