Skip to main content
VERSA provides a flexible installation process with a lightweight core package and optional metric-specific dependencies. This guide walks you through the installation options.

​
Prerequisites

Before installing VERSA, ensure you have:
  • Python 3.8 or higher
  • pip package manager
  • Git (for cloning the repository)
  • CUDA-compatible GPU (optional, for GPU-accelerated metrics)
Python 3.13 users: VERSA uses the latest Whisper commit to ensure compatibility with Python 3.13.

​
Basic Installation

The basic installation includes the core VERSA toolkit with many commonly used metrics.
1

Clone the Repository

Clone the VERSA repository from GitHub:
git clone https://github.com/wavlab-speech/versa.git
cd versa
2

Install the Package

Install VERSA using pip:
pip install .
This installs the core package with auto-installed metrics including:
  • PESQ, STOI for intelligibility
  • UTMOS, DNSMOS, NISQA for perceptual quality
  • MCD, F0 metrics for spectral analysis
  • Signal metrics (SDR, SAR, SIR, SI-SNR, CI-SDR)
  • Speaker similarity using ESPnet
3

Verify Installation

Test the installation with the core functionality test:
python versa/test/test_pipeline/test_general.py
You should see output confirming successful metric calculations:
Summary: {'mcd': 5.045, 'pesq': 1.572, 'stoi': 0.008, ...}
check successful

​
Alternative Installation (Without Cloning)

You can install VERSA directly from GitHub without cloning: 
python -m pip install git+https://github.com/wavlab-speech/versa.git#egg=versa-speech-audio-toolkit --no-build-isolation
This method installs only the basic package. You’ll still need to manually install metric-specific dependencies for advanced metrics.

​
Metric-Specific Dependencies

VERSA aligns with original APIs provided by algorithm developers rather than redistributing models. Some metrics require additional installation steps.

​
Understanding Auto-Install Status

In the supported metrics documentation, metrics are marked with an “x” in the “Auto-Install” column if they’re included in the basic installation. Metrics without an “x” require additional installation using the provided installers.

​
Installing Additional Metrics

1

Locate the Installer

Navigate to the tools directory:
cd tools
ls
You’ll see installation scripts for various metrics:
  • install_visqol.md - For ViSQOL metric
  • install_gitlfs.md - For Git LFS dependencies
  • Additional installers for specific metrics
2

Run the Installer

Follow the instructions in the relevant installer file. For example, to install ViSQOL:
# Follow instructions in tools/install_visqol.md
3

Test the Metric

Verify the metric installation with its specific test:
python versa/test/test_pipeline/test_{metric}.py
Replace {metric} with the metric name (e.g., test_wvmos.py, test_sigmos.py).

​
Common Optional Metrics

# Follow the installation guide
cat tools/install_visqol.md

# Test installation
python versa/test/test_pipeline/test_visqol.py

​
Development Installation

If you plan to contribute to VERSA or modify the source code:
1

Install with Dev Dependencies

pip install -e ".[dev]"
This installs:
  • pytest for testing
  • pytest-cov for coverage reports
  • black for code formatting
  • flake8 for linting
2

Run the Test Suite

pytest versa/test/
3

Check Code Style

black versa/
flake8 versa/

​
GPU Support

Many metrics support GPU acceleration for faster evaluation: 
python versa/bin/scorer.py \
    --score_config egs/speech.yaml \
    --pred audio.scp \
    --gt reference.scp \
    --output_file results \
    --use_gpu true
Multi-GPU Support: When running distributed evaluation, VERSA automatically assigns GPU ranks based on the --rank parameter and available devices.

​
Slurm Environment Setup

For large-scale distributed evaluation on HPC clusters:
1

Install VERSA on the Cluster

Follow the basic installation steps on your cluster’s compute nodes.
2

Verify Slurm Availability

which sbatch
sinfo
3

Configure Launch Scripts

Review and modify the Slurm launch scripts:
cat launch_slurm.sh
# Adjust partition, memory, and GPU requirements

​
Troubleshooting

Some metrics have optional dependencies. Check the error message for the missing package:
# If you see: "Please install pesq with `pip install pesq` and retry"
pip install pesq

# If you see: "Please install pystoi with `pip install pystoi` and retry"
pip install pystoi
Reduce batch size or evaluate metrics sequentially:
# Use CPU for memory-intensive metrics
python versa/bin/scorer.py \
    --score_config egs/speech_cpu.yaml \
    --use_gpu false
Some models require Git LFS:
# Install Git LFS
cat tools/install_gitlfs.md

# Re-clone with LFS
git lfs install
git lfs pull
VERSA uses a specific ESPnet branch. If you encounter issues:
pip uninstall espnet
pip install git+https://github.com/ftshijt/espnet.git@espnet_inference#egg=espnet

​
Verifying Your Installation

Run the comprehensive test to verify all installed metrics: 
# Test all basic metrics
python versa/test/test_pipeline/test_general.py

# Test individual metrics
python versa/test/test_pipeline/test_wer.py
python versa/test/test_pipeline/test_pam.py
python versa/test/test_pipeline/test_fad.py
Check installed metrics: Review egs/speech.yaml to see which metrics are configured by default, then cross-reference with the supported metrics documentation.

​
Next Steps

Quickstart Guide

Run your first evaluation with real audio samples

Configuration

Learn how to configure metrics and customize evaluations

Build docs developers (and LLMs) love

Get started for freeTalk to us