# CUDA Version Compatibility for Qwen3-TTS on Linux: Requirements and Setup Guide

> Learn Qwen3-TTS CUDA version compatibility for Linux. Ensure optimal performance with CUDA 11.8 or 12.0+. Avoid CPU fallback. Get the setup guide now.

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

---

**Qwen3-TTS requires CUDA 11.8 (driver ≥520.56) or CUDA 12.0+ (driver ≥525.60) when running on Linux via the faster-qwen3-tts backend, with automatic fallback to CPU if these requirements are not met.**

The `huggingface/speech-to-speech` repository provides a high-performance text-to-speech pipeline that includes the **Qwen3TTSHandler** for running Qwen3-TTS models. When deploying on Linux, understanding the CUDA version compatibility requirements is essential for GPU acceleration, as the handler automatically selects between CUDA-enabled and CPU-only backends based on your system configuration.

## How Qwen3-TTS Selects the Execution Backend on Linux

The `Qwen3TTSHandler` class automatically determines which audio backend to use based on the host platform. 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), the initialization logic checks the operating system and sets the backend accordingly:

```python

# Lines 51-55 in qwen3_tts_handler.py

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

```

On Linux (non-Darwin systems), the handler defaults to the **faster-qwen3-tts** library. This backend loads the model using the `FasterQwen3TTS` class from the pre-built GPU wheels:

```python

# Lines 21-29 and 102-110 in qwen3_tts_handler.py

from faster_qwen3_tts import FasterQwen3TTS

self.model = FasterQwen3TTS.from_pretrained(
    model_name, 
    device=self.device, 
    dtype=self.dtype, 
    backend=self.faster_backend,
    # ... additional parameters

)

```

The `device` parameter defaults to `"cuda"`, which triggers the CUDA runtime checks when the model initializes.

## CUDA Version Requirements for faster-qwen3-tts

The `faster-qwen3-tts` package ships with pre-built GPU wheels that link against specific CUDA toolkit versions. According to the package documentation and PyPI release metadata, the following combinations are supported:

| CUDA Toolkit | Minimum NVIDIA Driver Version |
|--------------|-------------------------------|
| **CUDA 11.8** | **520.56** or newer |
| **CUDA 12.0+** | **525.60** or newer |

If your installed CUDA runtime does not satisfy these requirements, the import will raise an `ImportError` indicating a binary mismatch. In such cases, the handler can fall back to the CPU-only **ggml** backend, though this results in significantly slower inference.

## Installing Qwen3-TTS with CUDA Support on Linux

To enable GPU acceleration, install the package with the `ggml` extra, which pulls the appropriate CUDA wheel if a compatible toolkit is detected:

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

```

Verify your CUDA environment before running the handler:

```python
import torch
assert torch.cuda.is_available(), "CUDA not detected – check driver/CUDA toolkit"
print(f"CUDA version: {torch.version.cuda}")
print(f"Driver version: {torch.cuda.get_device_properties(0).major}.{torch.cuda.get_device_properties(0).minor}")

```

Ensure your NVIDIA driver meets the minimum requirements:
- **CUDA 11.8 users**: Driver must be version **520.56** or higher
- **CUDA 12.0+ users**: Driver must be version **525.60** or higher

## Configuring the Handler for GPU and CPU Execution

### GPU Execution with CUDA

To force CUDA acceleration on Linux, instantiate the handler with `device="cuda"` and the `ggml` backend:

```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",               # Uses faster-qwen3-tts GPU kernels

    ggml_quantization="BF16",    # Selects compatible quantization for CUDA

)

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

```

### CPU-Only Fallback

If your system lacks compatible CUDA drivers, configure the handler for CPU inference:

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

    backend="ggml",              # Uses ggml CPU backend

    ggml_quantization="BF16",
)

handler.warmup()

```

### Runtime Backend Inspection

To verify which backend was selected at runtime:

```python
print(f"Backend in use: {handler.backend}")  

# Outputs: "faster_qwen3_tts" on Linux with CUDA

# Outputs: "mlx" on macOS

```

## Troubleshooting CUDA Compatibility Issues

When the CUDA runtime is incompatible, the handler will fail during the `faster_qwen3_tts` import or model initialization. Common resolution steps include:

1. **Check driver compatibility** – Run `nvidia-smi` to verify your driver version meets the 520.56 (CUDA 11.8) or 525.60 (CUDA 12.0+) thresholds
2. **Verify wheel installation** – Ensure you installed `faster-qwen3-tts[ggml]` rather than the base package
3. **Force CPU fallback** – Explicitly set `device="cpu"` and `backend="ggml"` to bypass CUDA requirements entirely

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 backend selection paths and error handling scenarios, providing reference implementations for handling missing libraries.

## Summary

- **Platform detection**: `Qwen3TTSHandler` 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) automatically selects `faster_qwen3_tts` on Linux and `mlx` on macOS
- **CUDA requirements**: Linux GPU support requires CUDA 11.8+ (driver ≥520.56) or CUDA 12.0+ (driver ≥525.60)
- **Installation**: Use `pip install "faster-qwen3-tts[ggml]"` to obtain CUDA-enabled wheels
- **Fallback option**: Set `device="cpu"` and `backend="ggml"` to run without CUDA dependencies
- **Verification**: Inspect `handler.backend` at runtime to confirm which execution path is active

## Frequently Asked Questions

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

The `faster-qwen3-tts` backend supports **CUDA 11.8** and **CUDA 12.0 or newer**. CUDA 11.8 requires NVIDIA driver version 520.56 or higher, while CUDA 12.0+ requires driver 525.60 or higher. These requirements are enforced by the pre-built binary wheels that `Qwen3TTSHandler` imports from [`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).

### How do I check if my NVIDIA driver is compatible with Qwen3-TTS?

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, use `torch.cuda.is_available()` in Python to verify that PyTorch can detect your GPU and CUDA runtime before initializing the handler.

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

Yes. Set `device="cpu"` and `backend="ggml"` when instantiating `Qwen3TTSHandler`. This configuration uses the CPU-only ggml backend instead of the CUDA-dependent `faster_qwen3_tts` library. While functional, CPU inference is significantly slower than GPU acceleration and is best suited for development or systems without NVIDIA hardware.

### Where does the backend selection logic live in the source code?

The automatic backend selection occurs 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, where the handler checks `if platform == "darwin"` to choose between `mlx` (macOS) and `faster_qwen3_tts` (Linux/Windows). The CUDA-specific model loading logic resides in the `_setup_faster()` method at lines 102-110, which imports `FasterQwen3TTS` and passes the `device` parameter directly to the underlying library.