Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.915 runs
timeout
glibcpy 3.10–3.915 runs
timeout
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pipeline
✓ from pyannote.audio import Pipeline
✗ from pyannote.audio.core.pipeline import Pipeline
The primary Pipeline class is directly available at the top-level `pyannote.audio` package since v2.x. Accessing it from internal modules like `pyannote.audio.core.pipeline` is discouraged and might break in future versions.
Model
✓ from pyannote.audio import Model
For loading individual models directly, e.g., for embedding or Voice Activity Detection.
Annotation
✓ from pyannote.core import Annotation
The core data structure for storing diarization results is part of the `pyannote.core` library.
Segment
✓ from pyannote.core import Segment
Used for representing time segments in annotations and other audio processing tasks, also part of `pyannote.core`.
This quickstart demonstrates how to set up `pyannote.audio`, authenticate with the Hugging Face Hub, and run a speaker diarization pipeline on a dummy audio file. It highlights the critical step of providing an authentication token for model access, a common requirement for `pyannote.audio` models since version 4.0.
import os
import torchaudio
import torch
import numpy as np
import tempfile
import shutil
# 1. Create a dummy audio file for demonstration
duration_seconds = 5
sample_rate = 16000
t = np.linspace(0, duration_seconds, int(sample_rate * duration_seconds), endpoint=False)
audio_data = 0.5 * np.sin(2 * np.pi * 440 * t).astype(np.float32)
temp_dir = tempfile.mkdtemp()
dummy_audio_path = os.path.join(temp_dir, "dummy_audio.wav")
torchaudio.save(dummy_audio_path, torch.from_numpy(audio_data).unsqueeze(0), sample_rate)
# 2. Authenticate with Hugging Face Hub
# Get your Hugging Face token from https://huggingface.co/settings/tokens
# and set it as an environment variable `HF_TOKEN` or replace the placeholder.
hf_token = os.environ.get("HF_TOKEN", "hf_YOUR_HUGGING_FACE_TOKEN_HERE")
if hf_token == "hf_YOUR_HUGGING_FACE_TOKEN_HERE":
print("WARNING: Please obtain a Hugging Face token from https://huggingface.co/settings/tokens ")
print("and set the HF_TOKEN environment variable or replace the placeholder in the code.")
print("Continuing with placeholder token; pipeline initialization might fail without proper authentication.")
# 3. Import and initialize the Pyannote.audio Pipeline
from pyannote.audio import Pipeline
pipeline = Pipeline("pyannote/speaker-diarization-3.1", use_auth_token=hf_token)
# 4. Prepare the audio input
demo_file = {"uri": "dummy_conversation", "audio": dummy_audio_path}
# 5. Run the speaker diarization
di_result = pipeline(demo_file)
# 6. Print the diarization result
print("\nDiarization Result:")
for turn, _, speaker in di_result.itertracks(yield_label=True):
print(f"start={turn.start:.1f}s stop={turn.end:.1f}s speaker={speaker}")
# 7. Clean up the dummy audio file
shutil.rmtree(temp_dir)
print(f"\nCleaned up temporary audio directory: {temp_dir}")
Errors
Common errors & fixes
TypeError: Pipeline.from_pretrained() got an unexpected keyword argument 'use_auth_token'
The `use_auth_token` parameter for authenticating with Hugging Face Hub models has been deprecated in recent versions of `pyannote.audio` (and `huggingface_hub`) and replaced with `token`.
fixReplace `use_auth_token` with `token` and ensure you are passing a valid Hugging Face access token. Also, make sure you have accepted the user conditions for the specific `pyannote.audio` model on the Hugging Face Hub.
AttributeError: module 'torchaudio' has no attribute 'set_audio_backend'
This error occurs when an older version of `pyannote.audio` (e.g., 3.1.0) tries to call `torchaudio.set_audio_backend('soundfile')`, but this function has been removed in `torchaudio` versions 2.2 and above.
fixUpgrade `pyannote.audio` to version 4.x or higher, which no longer uses `torchaudio.set_audio_backend` and instead relies on FFmpeg via `torchcodec`. Also, ensure your NumPy version is compatible (>=2.3).
'Could not load audio' Error
This error typically indicates that `pyannote.audio` is unable to access or process the provided audio file. Common reasons include an invalid, indirect, or inaccessible audio file URL, incorrect file permissions, an expired temporary URL, or the file exceeding size limits.
ModuleNotFoundError: No module named 'pyannote.core'
This error usually means that core components of the `pyannote` library, such as `pyannote.core` or `pyannote.audio.pipelines`, are not properly installed or accessible within your Python environment, often due to an incomplete or incorrect installation, or an outdated `pyannote.audio` version incompatible with other installed dependencies.
Segmentation Fault
Segmentation faults with `pyannote.audio` are often complex, stemming from underlying issues with `torch`, `torchaudio`, FFmpeg, or other low-level dependencies, especially in specific environments like Docker containers or on certain hardware (e.g., Raspberry Pi), indicating memory access violations.
Upgrade
Version history
4.0.7latest on PyPI · released Jun 30, 2026
Audit
Dependencies
torchrequiredDeep learning framework for model inference.
huggingface_hubrequiredRequired for downloading and authenticating pre-trained models from Hugging Face Hub.
onnxruntimeoptionalOptional backend for faster CPU inference.