Getting Started

Requirements

Python >=3.10 (Python 3.11 is the recommended default).
Linux/macOS environment (project is primarily validated on Linux).
CUDA-enabled PyTorch if you plan to train larger models on GPU.

Conda environment example

From README.md:

conda create --name ${your_env} python=3.11
conda activate ${your_env}

Install

Clone and install in editable mode:

git clone https://github.com/hyperion-ml/hyperion.git
cd hyperion
pip install -e .

PyTorch extras

The project defines optional extras to pin specific torch/torchaudio/torchvision combinations:

pip install -e .[torch29]

Other available extras are torch24, torch25, torch26, torch27, torch28, torch29.

CUDA wheel examples (from README)

Valid install commands by CUDA/PyTorch combo include:

pip install --extra-index-url https://download.pytorch.org/whl/cu130 -e .[torch29]
pip install --extra-index-url https://download.pytorch.org/whl/cu128 -e .[torch29]
pip install --extra-index-url https://download.pytorch.org/whl/cu126 -e .[torch29]
pip install --extra-index-url https://download.pytorch.org/whl/cu129 -e .[torch28]
pip install --extra-index-url https://download.pytorch.org/whl/cu128 -e .[torch28]
pip install --extra-index-url https://download.pytorch.org/whl/cu126 -e .[torch28]
pip install --extra-index-url https://download.pytorch.org/whl/cu128 -e .[torch27]
pip install --extra-index-url https://download.pytorch.org/whl/cu126 -e .[torch27]
pip install --extra-index-url https://download.pytorch.org/whl/cu124 -e .[torch26]
pip install --extra-index-url https://download.pytorch.org/whl/cu121 -e .[torch25]
pip install --extra-index-url https://download.pytorch.org/whl/cu121 -e .[torch24]

VoxProfile extra

To use VoxProfile wrappers under hyperion.torch.tpm.usc, install with the voxprofile extra:

pip install -e .[voxprofile]

You can combine extras:

pip install -e .[torch29,voxprofile]

Known issues

Older Linux systems (glibc `<= 2.17`)

From README.md:

pip install --extra-index-url https://download.pytorch.org/whl/cu121 \
  -e .[torch25,gcc217] --only-binary=:all: --no-binary=intervaltree,fairscale

MKL threading error during training

If you hit:

Error: mkl-service + Intel(R) MKL: MKL_THREADING_LAYER=INTEL is incompatible with libgomp.so.1 library.

The README workaround is to reinstall NumPy:

pip uninstall numpy
pip install numpy=={same-version-you-uninstalled}

Packaging and entry points

pyproject.toml is generated by generate_pyproject.py from proto_pyproject.toml.

The generator:

reads version from hyperion/__init__.py
reads dependencies from requirements.txt
scans hyperion/bin/*.py and creates [project.scripts] entry points

Regenerate when CLI scripts or dependencies change:

python generate_pyproject.py

Quick sanity checks

After installation, verify import and command registration:

python -c "import hyperion; print(hyperion.__version__)"
hyperion-train-qvector --help
hyperion-eval-verification-metrics --help