Install & Compatibility
Where this runs
tested against v6.1.1 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.216s · 167.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 9.3s · import 1.196s · 161MB
198MB installed
● package 198MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
registry
✓ from pyannote.database import registry
The primary interface for loading database configurations and accessing protocols since v5.0.0.
FileFinder
✓ from pyannote.database import FileFinder
A common preprocessor used to automatically locate media files associated with a URI within a protocol.
ProtocolFile
✓ from pyannote.database import ProtocolFile
Represents a multimedia resource with metadata, typically encountered when iterating over a protocol subset.
get_protocol
✓ protocol = registry.get_protocol('MyDatabase.MyProtocol')
✗ from pyannote.database import get_protocol; protocol = get_protocol('MyDatabase.MyProtocol')
The `get_protocol` function was removed in v5.0.0 and replaced by the `registry.get_protocol` method.
This quickstart demonstrates how to define a simple database protocol using a YAML configuration file, load it into the `pyannote.database` registry, and then iterate over a protocol subset to access multimedia resources and their associated metadata. It highlights the use of `registry.load_database` and `FileFinder`.
import os
from pathlib import Path
from pyannote.database import registry, FileFinder
# 1. Define your database protocol in a YAML file (e.g., database.yml)
# This example creates dummy files for demonstration purposes.
(Path("data") / "train.lst").parent.mkdir(parents=True, exist_ok=True)
(Path("data") / "train.lst").write_text("dummy_file_1\ndummy_file_2\n")
config_content = """
Protocols:
MyDatabase:
MyProtocol:
train:
uri: data/train.lst
"""
Path("database.yml").write_text(config_content)
# 2. Load the database configuration into the registry
# In a real scenario, you'd provide the actual path to your database.yml
# For demonstration, we ensure our dummy config is found.
os.environ["PYANNOTE_DATABASE_CONFIG"] = str(Path("database.yml").resolve())
registry.load_database("database.yml")
# 3. Access a specific protocol
# Use FileFinder as a preprocessor to resolve file paths for 'audio' or similar keys.
preprocessors = {'audio': FileFinder()}
protocol = registry.get_protocol("MyDatabase.MyProtocol", preprocessors=preprocessors)
# 4. Iterate over a subset (e.g., 'train') of the protocol
print("Iterating over training files:")
for current_file in protocol.train():
print(f" URI: {current_file['uri']}")
# In a real application, current_file['audio'] would resolve to the media file path,
# and current_file['annotation'] would provide temporal annotations.
# For this dummy example, 'audio' will not resolve to a real file path
# unless actual dummy audio files are created.
# 5. Clean up dummy files (not needed in a real application)
Path("database.yml").unlink()
(Path("data") / "train.lst").unlink()
Path("data").rmdir()
Errors
Common errors & fixes
FileNotFoundError: "pyannote.database" relies on a YAML configuration file but could not find any.
The `pyannote.database` library requires a YAML configuration file (e.g., `database.yml`) to define the paths to your multimedia databases and experimental protocols, and it could not locate this file in the expected locations (e.g., current working directory or `~/.pyannote/database.yml`).
fixCreate a `database.yml` file in your working directory or in `~/.pyannote/` that specifies your databases and protocols. Alternatively, explicitly load the configuration using `registry.load_database('/path/to/your/database.yml')` after importing `registry` from `pyannote.database`. ImportError: cannot import name 'registry' from 'pyannote.database'
This error typically occurs when using an older version of `pyannote.database` with code written for a newer API, or vice-versa. In recent versions (since 5.0), the way databases and protocols are accessed changed significantly, moving from direct functions like `get_database` or `get_protocol` to methods of a `registry` object.
fixEnsure your `pyannote.database` version is compatible with your code. For versions 5.0 and newer, import `registry` and use its methods: `from pyannote.database import registry; registry.load_database('your_config.yml'); database = registry.get_database('MyDatabase')`. AttributeError: 'ProtocolFile' object has no attribute 'dim'
This `AttributeError` often arises when a `ProtocolFile` object is incorrectly passed to a function or model that expects a different input type, such as an `Audio` object or a specific feature representation, especially in the context of `pyannote.audio` models that have specific input requirements.
fixReview the documentation or examples for the specific model or function you are using to understand the expected input type. You might need to preprocess the `ProtocolFile` (e.g., load the audio, extract features) before passing it to the model. For instance, ensure you are passing the correct part of the file or converting it to the expected format before feeding it to a `Model` or `Pipeline`.
ModuleNotFoundError: No module named 'pyannote.core'
This error indicates that the `pyannote.core` library, a fundamental dependency for `pyannote.database` and other `pyannote` ecosystem components, is not installed or not accessible in your Python environment.
fixInstall `pyannote.core` using pip: `pip install pyannote.core`. Ensure your Python environment is correctly activated if you are using virtual environments. If using `pyannote.audio`, it is often recommended to install `pyannote.audio` which should pull `pyannote.core` as a dependency.
ValueError: No loader for files with '.rttm' suffix
This error occurs when `pyannote.database` attempts to load a file with a specific suffix (e.g., `.rttm`) but does not have a registered data loader for that file type. This can happen if the necessary loader is not imported, not properly configured, or if there were breaking changes in how loaders are registered across library versions.
fixEnsure that the appropriate data loader is imported and registered. For `.rttm` files, you might need to explicitly import `load_rttm` from `pyannote.database.util`. If using custom loaders, make sure they are correctly defined and registered as entry points. Verify your `pyannote.database` version as loader mechanisms might evolve across major releases.
Upgrade
Version history
6.1.1latest on PyPI · released Dec 7, 2025
Audit
Dependencies
pandasrequiredData manipulation for loaders
pyannote-corerequiredProvides core data structures for temporal segments and annotations
pyyamlrequiredFor parsing YAML configuration files