← Back to the Server setup guide

Setting Up WhisperX on Windows + WSL + NVIDIA GPU

This guide walks you through setting up WhisperX with NVIDIA GPU acceleration on Windows using WSL (Windows Subsystem for Linux). After completing these steps, your machine will be ready to run the LymeScribe server.

Prerequisites Checklist

Before starting, confirm you have:

1. Install WSL

Open PowerShell as Administrator and run:

wsl --install

This installs WSL2 with Ubuntu as the default distribution. Restart your computer when prompted.

Note: WSL2 is required — WSL1 does not support GPU passthrough. If you previously installed WSL1, upgrade with wsl --set-default-version 2.

After restarting, Ubuntu will launch automatically and prompt you to create a Linux username and password. Complete this setup.

Verify WSL is Running

Open a new PowerShell window and run:

wsl --list --verbose

Expected output:

  NAME      STATE           VERSION
* Ubuntu    Running         2

Confirm the VERSION column shows 2.

2. Set Up Ubuntu in WSL

Open the Ubuntu terminal (search for "Ubuntu" in the Start menu, or type wsl in PowerShell).

Update Package Lists

sudo apt-get update && sudo apt-get upgrade -y

Install System Dependencies

sudo apt-get install -y python3-pip python3-venv python3-full ffmpeg

Verify ffmpeg

ffmpeg -version

Expected output (first line):

ffmpeg version 4.4.x-0ubuntu... Copyright (c) 2000-2024 the FFmpeg developers

The exact version number may differ. As long as ffmpeg runs without error, you are good.

3. Verify CUDA Access in WSL

NVIDIA GPU drivers installed on Windows are automatically shared with WSL2 — you do not need to install a separate CUDA driver inside WSL.

Note: The Windows NVIDIA driver handles GPU passthrough to WSL2. You only need the latest Windows driver installed.

Verify GPU Access

nvidia-smi

Expected output (example):

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 560.94                 Driver Version: 560.94         CUDA Version: 12.6     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 ...           |                        |                      |
|   0  NVIDIA GeForce RTX 4070 Ti         |                        |                      |
+-----------------------------------------+------------------------+----------------------+

You should see your GPU name, driver version, and CUDA version. If this command fails, see Troubleshooting.

Install cuDNN (CUDA Deep Neural Network Library)

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get install -y libcudnn8

4. Create Python Virtual Environment and Install WhisperX

Create and Activate the Virtual Environment

python3 -m venv ~/whisper-env
source ~/whisper-env/bin/activate

After activation, your terminal prompt will show (whisper-env) at the beginning.

Upgrade pip

pip install --upgrade pip

Install WhisperX

pip install whisperx==3.8.6

Install Speaker Diarization Support

pip install pyannote.audio==4.0.4

Note: These installations may take several minutes as they download PyTorch, CUDA libraries, and model dependencies.

5. HuggingFace Setup

Complete the HuggingFace Account Setup guide to create your account, generate an access token, and accept the required model license terms.

6. Test Your Setup

With the virtual environment still activated, run a test to verify everything works.

Verify CUDA is Available in Python

python3 -c "import torch; print('CUDA available:', torch.cuda.is_available()); print('GPU:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'None')"

Expected output:

CUDA available: True
GPU: NVIDIA GeForce RTX 4070 Ti

Verify WhisperX is Installed

python3 -c "import whisperx; print('WhisperX imported successfully')"

Expected output:

WhisperX imported successfully

Run a Test Transcription

Create a short audio file or use any .mp3/.wav file you have available:

export HF_TOKEN="your_huggingface_token_here"
whisperx "test-audio.mp3" --model large-v2 --device cuda --diarize --hf_token $HF_TOKEN --output_format all

If the transcription completes and produces .json, .srt, .txt, .vtt, and .tsv output files, your setup is working correctly.

Note: The first run will download the large-v2 model (~3 GB) and diarization models. This is a one-time download.

Troubleshooting

nvidia-smi not found or shows no GPU

WSL networking issues / DNS resolution failures

If apt-get update or pip install fails with connection errors:

# Check if DNS is working
ping -c 1 google.com

If DNS fails, create or edit /etc/resolv.conf:

sudo rm /etc/resolv.conf
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

To make this persist across WSL restarts, add to /etc/wsl.conf:

sudo tee /etc/wsl.conf << 'EOF'
[network]
generateResolvConf = false
EOF

Then restart WSL from PowerShell: wsl --shutdown and reopen Ubuntu.

Virtual environment activation problems

If source ~/whisper-env/bin/activate fails:

"No module named whisperx" errors

cuDNN errors during transcription

Out of VRAM errors