WhisperX installation: plan a clean local setup

Start with the current upstream requirements

WhisperX dependencies change between releases. Read the project README and the requirements for the release you choose before selecting Python, PyTorch, or CUDA versions. This is a documentation based setup guide; it is not a claim that every command has been tested on your operating system.

Use a separate Python environment

Create a fresh virtual environment rather than mixing speech tools into an existing application environment. Save the version of WhisperX you installed and your dependency lockfile with the project. Follow the stable release instructions when reproducibility matters more than trying the newest development commit.

python -m venv .venv
# Activate .venv using the command for your shell
python -m pip install --upgrade pip
python -m pip install whisperx

Decide between CPU and a compatible GPU

CPU mode is an option for environments without a compatible NVIDIA setup. GPU acceleration requires a matching driver and software stack; CUDA alone is not a guarantee that PyTorch or CTranslate2 will load. FFmpeg is also needed to read common media formats. Verify each dependency before attempting a long recording.

whisperx recording.wav --device cpu --compute_type int8

Add diarization only after transcription works

First get a short recording transcribed and aligned. Then configure the model access requirements described upstream for speaker diarization. Accept the relevant model’s conditions with your own account and store the access token outside source control. Do not paste tokens into public issue reports.

Troubleshoot one layer at a time

A missing executable points to the shell environment. A CUDA or cuDNN load error points to the accelerator stack. A memory error often calls for a smaller batch. A model access error calls for checking permissions. A successfully completed command with a weak transcript calls for inspecting the recording and model output, rather than reinstalling everything.

• Capture the exact command and package versions.
• Reproduce on a short file before retrying a long job.
• Reduce batch size before choosing a different model.
• Remove tokens and private file paths from shared logs.

Choose hosting when setup is the obstacle

WhisperX runs the processing environment for you. It is useful when you want the output without maintaining the local stack. Local installation remains a good fit when you need your own configuration, control of data location, or a pipeline you manage yourself.