Install & Compatibility
Where this runs
tested against v4.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ timeout
py 3.11
✕ build_error
✕ timeout
py 3.12
✕ build_error
✕ timeout
py 3.13
✕ build_error
✓ 86.1s
py 3.9
✕ build_error
✕ timeout
5325MB installed
● package 5325MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Pipeline
✓ from pyannote.audio import Pipeline
ProgressHook
✓ from pyannote.audio.pipelines.utils.hook import ProgressHook
Optional, for monitoring pipeline progress.
This quickstart demonstrates how to load a pretrained speaker diarization pipeline from Hugging Face. It highlights the critical need for a Hugging Face access token, stored as an environment variable, and acceptance of the model's user conditions. The example then shows how to instantiate the pipeline and prepare to apply it to an audio file. Note that `ffmpeg` must be installed on your system for audio processing.
import os
from pyannote.audio import Pipeline
# Ensure you have a Hugging Face access token set as an environment variable
# and have accepted user conditions for 'pyannote/speaker-diarization-community-1'
# on hf.co/pyannote/speaker-diarization-community-1
hf_token = os.environ.get('HUGGINGFACE_ACCESS_TOKEN', '')
if not hf_token:
print("Error: HUGGINGFACE_ACCESS_TOKEN environment variable not set.")
print("Please create a token at hf.co/settings/tokens and set it.")
exit()
# Instantiate a pretrained speaker diarization pipeline
try:
pipeline = Pipeline.from_pretrained(
"pyannote/speaker-diarization-community-1",
token=hf_token
)
except Exception as e:
print(f"Failed to load pipeline: {e}")
print("Make sure your Hugging Face token is valid and you've accepted user conditions.")
exit()
# Example: Apply the pipeline to an audio file (replace 'audio.wav' with your path)
# For demonstration, we'll simulate a file path.
# In a real scenario, you would have 'audio.wav' present.
audio_file_path = "dummy_audio.wav" # Replace with actual audio file path
# This part of the code is illustrative as 'dummy_audio.wav' won't exist.
# You would typically pass a real audio file path here.
print(f"Attempting to apply pipeline to {audio_file_path}...")
# For actual execution, ensure 'ffmpeg' is installed and 'audio.wav' exists.
# output = pipeline(audio_file_path)
# print("Diarization results:")
# for turn, speaker in output.speaker_diarization:
# print(f"start={turn.start:.1f}s stop={turn.end:.1f}s speaker={speaker}")
print("Pipeline loaded successfully. To run, replace 'dummy_audio.wav' with your audio file and ensure ffmpeg is installed.")
print("Note: The actual application of the pipeline to 'dummy_audio.wav' is commented out as it requires a real audio file and ffmpeg.")
Debug
Known issues
breaking`pyannote.audio` (which includes `pyannote-pipeline`) version 4.0.0 requires Python 3.10 or newer. Older Python versions are no longer supported.fixUpgrade your Python environment to 3.10 or later.
affects: 4.0.0 and higher
breakingThe `use_auth_token` argument in `Pipeline.from_pretrained()` has been renamed to `token`.fixReplace `use_auth_token=...` with `token=...` when calling `Pipeline.from_pretrained()`.
affects: 4.0.0 and higher
gotchaAccessing pretrained pipelines from Hugging Face requires accepting user conditions and providing a Hugging Face access token (e.g., via `token=os.environ.get('HUGGINGFACE_ACCESS_TOKEN')`). Failure to do so will result in authentication errors.fixVisit `hf.co/settings/tokens` to create a token, and accept the user conditions for the specific `pyannote` models you intend to use (e.g., `hf.co/pyannote/speaker-diarization-community-1`). Provide the token in your code.
affects: All versions using Hugging Face models
gotchaThe library relies on `ffmpeg` for audio decoding. `ffmpeg` is an external dependency and must be installed separately on your operating system (it is not installed via pip).fixInstall `ffmpeg` on your system. Refer to `ffmpeg.org/download.html` for installation instructions.
affects: All versions
breakingIn `pyannote.audio` 4.0.0, multi-channel audio is no longer automatically downmixed to mono by default. If your workflow involves `pyannote.audio.core.io.Audio` and expects mono conversion, this behavior has changed.fixExplicitly set `mono="downmix"` when instantiating `Audio()` for multi-channel audio: `Audio(mono="downmix")`.
affects: 4.0.0 and higher
deprecated`onnxruntime` is no longer a direct dependency of `pyannote.audio`. If you are using models that rely on ONNX, you will need to install `onnxruntime` manually.fixIf you use ONNX-based models, ensure you install `onnxruntime` explicitly: `pip install onnxruntime`.
affects: 4.0.0 and higher
Errors
Common errors & fixes
ImportError: cannot import name 'Pipeline' from 'pyannote.audio'
This error typically occurs when an older or incompatible version of `pyannote.audio` is installed, or the import path for `Pipeline` is incorrect, as its location changed in newer versions.
fixEnsure `pyannote.audio` version 4.0.0 or later is installed via `pip install --upgrade pyannote.audio` and use `from pyannote.audio import Pipeline`.
AttributeError: module 'torchaudio' has no attribute 'set_audio_backend'
This issue arises from an incompatibility between an older `pyannote.audio` version (e.g., 3.x) and newer `torchaudio` versions (2.2 or later), where `set_audio_backend` was removed; `pyannote.audio` version 4.x addresses this by removing the deprecated call.
fixUpgrade `pyannote.audio` to version 4.0.0 or later using `pip install --upgrade pyannote.audio` to ensure compatibility with recent `torchaudio` versions.
Could not download 'pyannote/speaker-diarization' pipeline. It might be because the pipeline is private or gated so make sure to authenticate. Visit https://hf.co/settings/tokens to create your access token and retry with: >>> Pipeline.from_pretrained('pyannote/speaker-diarization', ... use_auth_token='hf...')
This error indicates that the user is trying to access a gated Hugging Face model without proper authentication or is using the deprecated `use_auth_token` argument instead of `token` with `Pipeline.from_pretrained` in `pyannote.audio` v4.x.
fixFirst, visit the model's Hugging Face page to accept its user conditions. Then, generate a Hugging Face access token and pass it using the `token` argument: `pipeline = Pipeline.from_pretrained('pyannote/speaker-diarization', token='YOUR_HF_TOKEN')`. RuntimeError: A pipeline must be instantiated with `pipeline.instantiate(parameters)` before it can be applied.
When loading a pipeline from a YAML configuration file, `Pipeline.from_pretrained()` or similar loading methods might return a pipeline object that requires explicit instantiation with a `parameters` dictionary before it can be used to process audio.
fixAfter loading the pipeline from the configuration, call `pipeline.instantiate(parameters)` with the necessary configuration parameters: `pipeline = Pipeline.from_pretrained("config.yaml"); pipeline.instantiate(params)`. ModuleNotFoundError: No module named 'pyannote.core'
The `pyannote.core` library, a fundamental dependency for `pyannote.audio` and `pyannote-pipeline`, is either not installed or not correctly recognized in the current Python environment.
fixEnsure `pyannote.audio` and its dependencies, including `pyannote.core`, are properly installed by running `pip install pyannote.audio`.
Upgrade
Version history
4.0.0latest on PyPI · released Sep 9, 2025
Audit
Dependencies
pyannote.audiorequiredCore library that provides the audio processing functionalities and models.
torchrequiredUnderlying machine learning framework for neural network operations.
huggingface_hubrequiredRequired for downloading and loading pretrained models and pipelines from Hugging Face.
ffmpegrequiredExternal dependency for audio decoding and processing (must be installed separately on the system).