# How to Configure CUDA Versions for Qwen3-TTS on Linux Systems

> Configure CUDA for Qwen3-TTS on Linux. Install CUDA 11.8+ or 12.0+, then accelerate Qwen3-TTS with `faster-qwen3-tts[ggml]` on your GPU.

- Repository: [Hugging Face/speech-to-speech](https://github.com/huggingface/speech-to-speech)
- Tags: how-to-guide
- Published: 2026-08-10

---

**Configure CUDA versions for Qwen3-TTS by installing CUDA 11.8 or newer (driver ≥520.56) or CUDA 12.0+ (driver ≥525.60), then install `faster-qwen3-tts[ggml]` and initialize `Qwen3TTSHandler` with `device="cuda"` and `backend="ggml"` to enable GPU acceleration.**

The `huggingface/speech-to-speech` repository implements high-performance text-to-speech generation through the `Qwen3TTSHandler` class. When deploying on Linux systems, proper CUDA configuration determines whether the handler leverages GPU acceleration via the `faster-qwen3-tts` backend or falls back to CPU-only inference. Understanding the version requirements and initialization parameters ensures optimal performance across different Linux distributions.

## Platform-Specific Backend Selection

The `Qwen3TTSHandler` automatically detects the host platform to select the appropriate execution backend. In [`src/speech_to_speech/TTS/qwen3_tts_handler.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/TTS/qwen3_tts_handler.py), lines 51-55 implement this logic:

```python
self.backend = "mlx" if platform == "darwin" else "faster_qwen3_tts"

```

On Linux systems, this assignment selects the `faster_qwen3_tts` backend, which loads the `FasterQwen3TTS` class from the `faster-qwen3-tts` package. This backend relies on pre-built CUDA wheels that require specific NVIDIA driver and toolkit versions to function correctly.

## CUDA Version and Driver Requirements

The `faster-qwen3-tts` library ships with GPU-enabled wheels that depend on the system's CUDA toolkit installation. Configure CUDA versions for Qwen3-TTS according to the following compatibility matrix:

- **CUDA 11.8**: Requires NVIDIA driver version **520.56** or newer
- **CUDA 12.0+**: Requires NVIDIA driver version **525.60** or newer

If the installed CUDA runtime cannot satisfy these requirements, importing `faster_qwen3_tts` raises an `ImportError` indicating a binary mismatch. The handler will then fall back to the CPU-only ggml backend, which remains functional but significantly slower than GPU acceleration.

## Installing CUDA-Compatible Dependencies

Install the GPU-enabled wheel with the ggml extra to pull the appropriate CUDA binaries:

```bash
pip install "faster-qwen3-tts[ggml]"

```

Verify your CUDA installation before initializing the handler:

```python
import torch

assert torch.cuda.is_available(), "CUDA not detected – check driver/CUDA toolkit"
print(f"CUDA version: {torch.version.cuda}")

```

## Configuring the Handler for GPU Execution

To enable CUDA acceleration, initialize `Qwen3TTSHandler` with explicit device mapping. The `_setup_faster()` method in [`src/speech_to_speech/TTS/qwen3_tts_handler.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/TTS/qwen3_tts_handler.py) passes the `device` parameter directly to `FasterQwen3TTS.from_pretrained()`:

```python
from threading import Event
from speech_to_speech.TTS.qwen3_tts_handler import Qwen3TTSHandler

handler = Qwen3TTSHandler(
    should_listen=Event(),
    model_name="Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
    device="cuda",                # Forces GPU execution

    backend="ggml",               # Required for faster-qwen3-tts integration

    ggml_quantization="BF16",    # Compatible quantization for CUDA

)

handler.warmup()  # Loads model and validates CUDA compatibility

```

## CPU-Only Fallback Configuration

For systems lacking compatible CUDA installations, configure the handler for CPU execution by changing the device parameter:

```python
handler = Qwen3TTSHandler(
    should_listen=Event(),
    model_name="Qwen/Qwen3-TTS-12Hz-0.6B-Base",
    device="cpu",                 # Forces CPU execution

    backend="ggml",               # CPU-compatible backend

    ggml_quantization="BF16",
)

handler.warmup()

```

## Runtime Verification and Testing

Inspect the active backend at runtime to confirm your CUDA configuration:

```python
print(f"Backend in use: {handler.backend}")  # Returns "faster_qwen3_tts" on Linux with CUDA

```

The test suite in [`tests/test_qwen3_tts_handler_backend.py`](https://github.com/huggingface/speech-to-speech/blob/main/tests/test_qwen3_tts_handler_backend.py) validates these configuration paths, including error handling when required CUDA libraries are absent.

## Summary

- Configure CUDA versions for Qwen3-TTS by ensuring CUDA 11.8+ (driver ≥520.56) or CUDA 12.0+ (driver ≥525.60) is installed on your Linux system
- Install GPU dependencies using `pip install "faster-qwen3-tts[ggml]"`
- Set `device="cuda"` and `backend="ggml"` in `Qwen3TTSHandler` to enable GPU acceleration via the `faster_qwen3_tts` backend
- The backend selection logic resides in [`src/speech_to_speech/TTS/qwen3_tts_handler.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/TTS/qwen3_tts_handler.py) at lines 51-55
- Use `device="cpu"` for systems without NVIDIA GPUs or compatible CUDA toolkits

## Frequently Asked Questions

### What CUDA versions are supported by Qwen3-TTS?

Qwen3-TTS supports CUDA 11.8 or newer through the `faster-qwen3-tts` package. Specifically, CUDA 11.8 requires NVIDIA driver 520.56 or higher, while CUDA 12.0 and above requires driver 525.60 or higher. These requirements ensure compatibility with the pre-built GPU wheels shipped with the package.

### How do I check if my NVIDIA driver is compatible?

Run `nvidia-smi` in your terminal to display the current driver version. Compare this against the minimum requirements: 520.56 for CUDA 11.8 or 525.60 for CUDA 12.0+. Alternatively, import `torch` and execute `torch.cuda.is_available()` to verify that PyTorch detects your GPU and CUDA runtime correctly.

### Can I run Qwen3-TTS without CUDA on Linux?

Yes, set `device="cpu"` when initializing `Qwen3TTSHandler`. This configuration uses the ggml backend for CPU-only inference, which does not require NVIDIA drivers or CUDA toolkit installation. While functional, CPU inference runs significantly slower than GPU-accelerated generation.

### Where is the backend selection logic implemented?

The platform detection and backend selection logic is implemented in [`src/speech_to_speech/TTS/qwen3_tts_handler.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/TTS/qwen3_tts_handler.py) at lines 51-55. This code checks the system platform and sets `self.backend` to `"mlx"` for macOS systems or `"faster_qwen3_tts"` for Linux and Windows, determining which underlying library handles the text-to-speech generation.