Install & Compatibility
Where this runs
tested against v1.1.135 · 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
✕ build_error
py 3.9
✕ build_error
✕ build_error
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
BackgroundTask
✓ from music_assistant_models import BackgroundTask
✗ from music_assistant_models.metadata import Track
TaskSchedule
✓ from music_assistant_models import TaskSchedule
TaskStatus
✓ from music_assistant_models import TaskStatus
This quickstart demonstrates how to import and instantiate core media item models like `Artist`, `Album`, and `Track`, as well as interacting with common enums. It highlights the use of Pydantic V2 methods for serialization.
from music_assistant_models.metadata import Track, Artist, Album
from music_assistant_models.enums import MediaType
from music_assistant_models.player import PlayerState, RepeatMode
# Example: Create a simple Artist object
artist = Artist(
item_id="artist_123",
provider="spotify",
name="The Example Band",
media_type=MediaType.ARTIST
)
# Example: Create an Album object
album = Album(
item_id="album_456",
provider="spotify",
name="Greatest Hits",
artists=[artist],
year=2023,
media_type=MediaType.ALBUM
)
# Example: Create a Track object
track = Track(
item_id="track_789",
provider="spotify",
name="Sample Song",
version="Original Mix",
duration=240, # seconds
artists=[artist],
album=album,
media_type=MediaType.TRACK
)
print(f"Created Track: {track.name} by {', '.join(a.name for a in track.artists)}")
print(f"Track duration: {track.duration} seconds from album '{track.album.name}'")
# Accessing model attributes
print(f"Track media type: {track.media_type.value}")
# Using other enums
print(f"Current PlayerState options: {list(PlayerState)}")
print(f"Desired RepeatMode: {RepeatMode.ALL}")
# To serialize a model to JSON (Pydantic V2 style)
import json
print("\nSerialized Track (JSON):")
print(json.dumps(track.model_dump(), indent=2))
Debug
Known issues
breaking`music-assistant-models` specifically requires Pydantic V2 (>=2.0.0). Using Pydantic V1 will result in `ImportError` or `AttributeError` during model instantiation or method calls.fixEnsure your environment has Pydantic V2 installed by running `pip install 'pydantic>=2.0.0'`.
affects: All 1.x versions
breakingThis library explicitly requires Python 3.11 or newer. Attempting to install or run on older Python versions (e.g., 3.10) will cause installation failures or runtime errors.fixUpgrade your Python environment to 3.11 or later. Consider using `pyenv` or `conda` to manage multiple Python versions.
affects: All 1.x versions
gotchaIf you are migrating from Pydantic V1, be aware that many common methods have been renamed in V2. For example, `parse_obj` is now `model_validate`, `dict()` is `model_dump()`, and `json()` is `model_dump_json()`.fixRefer to the Pydantic V2 migration guide for a full list of method renames and API changes. Use `model_validate()` for creating models from dictionaries and `model_dump()`/`model_dump_json()` for serialization.
affects: Users familiar with Pydantic V1 syntax
Upgrade
Version history
1.1.135latest on PyPI · released Jun 16, 2026
Audit
Dependencies
pydanticrequiredUsed for defining all core data models (requires V2+).
msgspecrequiredEfficient serialization/deserialization.
orjsonrequiredFast JSON serialization.
semverrequiredSemantic versioning utilities.
async-timeoutrequiredAsynchronous operations timeout.