WhisperX setup — install, alignment, diarization errors fixed

Install WhisperX for word-accurate timestamps and speaker diarization, and fix the classic failures: pyannote auth token errors, CUDA/cuDNN mismatches, alignment model downloads.

Setup that works

1

Install

pip install whisperx in a fresh venv, Python 3.9–3.11. GPU needs a torch build matching your CUDA version FIRST, then whisperx.

2

Basic run

whisperx audio.mp3 --model large-v2 --align_model WAV2VEC2_ASR_LARGE_LV60K_960H

3

Diarization

--diarize needs a Hugging Face token with pyannote terms accepted: --hf_token hf_…

Skip the setup — paste the file here

Same Whisper-class accuracy, no install, no model downloads, no GPU questions. Speaker labels, word timestamps and every export (TXT, SRT, VTT, DOCX) included. Free instant preview; credits from $2 and they never expire.

Fixing the common errors

“Could not download pyannote model” / 401

You must accept the user conditions for BOTH pyannote/segmentation-3.0 and pyannote/speaker-diarization-3.1 on Hugging Face while logged in, then pass a token that has read scope.

CUDA error / cuDNN version mismatch

faster-whisper wheels are built against specific cuDNN versions. Match torch + CUDA first (pip install torch --index-url https://download.pytorch.org/whl/cu121), then reinstall whisperx.

Alignment fails for my language

wav2vec2 alignment models exist for ~10 languages; for others WhisperX falls back to segment timestamps. Check the supported list before promising word-level output.

Out of memory on large-v2

Use --compute_type int8 (halves VRAM, minor accuracy cost) or --batch_size 4.

It's slower than advertised

The 70× realtime figure is GPU batch mode. CPU runs are roughly realtime; if you don't have an NVIDIA GPU, a hosted run is usually faster end-to-end.

More on WhisperX: the full WhisperX page · WhisperX alternatives · all transcription tools