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

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:

# Method 1: Check driver-level CUDA version

nvidia-smi

# 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

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

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:

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:

# 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:

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:

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:

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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}