# How to Handle CUDA Version Mismatches with Qwen3-TTS on Linux

> Resolve Qwen3-TTS CUDA version mismatches on Linux. Install the correct qwentts-cpp-python wheel before speech-to-speech for seamless GGML backend loading and prevent errors.

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

---

**Install the `qwentts-cpp-python` wheel that matches your system's CUDA runtime (e.g., `cu124` for CUDA 12.4) before installing `speech-to-speech` to eliminate version-mismatch errors when loading the GGML backend.**

Qwen3-TTS in the `huggingface/speech-to-speech` repository uses the **faster-qwen3-tts** GGML backend, which depends on platform-specific binary wheels. The default PyPI wheel targets CUDA 12.8, but most Linux systems run older CUDA versions. This guide shows how to align your installation with your CUDA runtime to prevent import failures.

## Detect Your CUDA Runtime Version

Before installing any wheels, determine which CUDA version your system supports. Run either of these commands:

```bash

# Method 1: Check driver-level CUDA version

nvidia-smi

```

```bash

# Method 2: Check toolkit version

nvcc --version

```

Look for the **CUDA Version** field. Common values include 12.4, 12.3, 11.8, or older 11.x releases. The `qwentts-cpp-python` project provides pre-built wheels for `cu124`, `cu128`, `cu130`, and CPU-only environments.

## Install the Matching Qwen3-TTS Wheel

The repository hosts compatible wheels on Hugging Face Hub. Select the wheel tag that matches your detected CUDA version.

### For CUDA 12.4 Systems

```bash
pip install "qwentts-cpp-python==0.3.1+cu124" \
  -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu124

```

### For CUDA 12.8 Systems

```bash
pip install "qwentts-cpp-python==0.3.1+cu128" \
  -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu128

```

### For CPU-Only Systems

If no compatible GPU is available, use the CPU wheel to avoid CUDA dependencies entirely:

```bash
pip install "qwentts-cpp-python==0.3.1+cpu" \
  -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cpu

```

## Complete Installation Workflow

After installing the correct wheel, proceed with the main `speech-to-speech` package:

```bash

# Step 1: Install matching wheel (example for CUDA 12.4)

pip install "qwentts-cpp-python==0.3.1+cu124" \
  -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu124

# Step 2: Install the speech-to-speech library

pip install speech-to-speech

```

Verify the installation by running a minimal pipeline:

```python
from speech_to_speech.pipeline.s2s_pipeline import SpeechToSpeechPipeline

pipeline = SpeechToSpeechPipeline(
    stt="whisper",
    tts="qwen3",
    qwen3_tts_device="cuda",      # Uses the GPU backend you installed

    qwen3_tts_backend="ggml",     # Default GGML backend

)

pipeline.run()

```

## Switching to the Torch Backend

The `qwen3_tts_backend` parameter in `Qwen3TTSHandlerArguments` accepts `"ggml"` (default) or `"torch"`. To use the torch CUDA-graph backend instead, install a wheel with CUDA 13.0 support:

```bash
pip install "qwentts-cpp-python==0.3.1+cu130" \
    -f https://huggingface.co/datasets/andito/qwentts-cpp-python-wheels/tree/main/whl/cu130

```

Then instantiate the pipeline with the torch backend:

```python
pipeline = SpeechToSpeechPipeline(
    stt="whisper",
    tts="qwen3",
    qwen3_tts_device="cuda",
    qwen3_tts_backend="torch",    # Switches to torch CUDA graphs

)

```

Backend selection logic resides in [`src/speech_to_speech/arguments_classes/qwen3_tts_arguments.py`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/arguments_classes/qwen3_tts_arguments.py) at lines 31-36.

## Where Errors Originate

If the wrong wheel is installed, `Qwen3TTSHandler.setup()` 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) raises an import error when attempting to load `faster_qwen3_tts`. The handler initializes the **mlx** backend on macOS or **faster_qwen3_tts** on Linux, and fails explicitly if the required native binaries are incompatible with your CUDA runtime.

The project's README documents this issue at lines 101-108, and [`src/speech_to_speech/TTS/README.md`](https://github.com/huggingface/speech-to-speech/blob/main/src/speech_to_speech/TTS/README.md) repeats the installation commands at lines 100-108 for discoverability.

## Summary

- **Detect** your CUDA version with `nvidia-smi` or `nvcc --version`
- **Match** the `qwentts-cpp-python` wheel tag (`cu124`, `cu128`, `cu130`, or `cpu`) to your runtime
- **Install** the wheel from the Hugging Face Hub index before `speech-to-speech`
- **Verify** by running a pipeline with `qwen3_tts_backend="ggml"` or `"torch"`

## Frequently Asked Questions

### What CUDA versions are officially supported for Qwen3-TTS?

Pre-built wheels exist for CUDA 12.4 (`cu124`), 12.8 (`cu128`), and 13.0 (`cu130`), plus a CPU-only variant. According to the `huggingface/speech-to-speech` source code, these are the validated targets for the GGML backend. If your system runs CUDA 11.x, use the CPU wheel or upgrade your NVIDIA driver to support CUDA 12.x.

### Why does Qwen3-TTS fail with "ImportError: cannot import name faster_qwen3_tts"?

This error occurs in `Qwen3TTSHandler.setup()` when the `qwentts-cpp-python` wheel either is not installed or was compiled for an incompatible CUDA version. The native library fails to load, causing the handler to raise an import error. Reinstall the wheel that matches your `nvidia-smi` CUDA version.

### Can I use Qwen3-TTS without any GPU?

Yes. Install the CPU wheel with `+cpu` tag instead of a CUDA variant. The pipeline runs entirely on CPU with reduced throughput. The `qwen3_tts_device` parameter accepts `"cpu"` to force CPU execution.

### How do I switch between GGML and torch backends after installation?

Change the `qwen3_tts_backend` argument when constructing `SpeechToSpeechPipeline` or via CLI. The option is defined in `Qwen3TTSHandlerArguments` with choices `["ggml", "torch"]`. Ensure your installed wheel supports the CUDA version required by your selected backend, as torch may require newer CUDA features than GGML.