Install & Compatibility
Where this runs
tested against v1.3.4 · 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
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MusicAssistantClient
✓ from music_assistant_client import MusicAssistantClient
✗ from musicassistantclient import MusicAssistantClient
Python package names often convert hyphens to underscores for import paths. Do not use the hyphenated package name directly for imports.
MusicAssistantError
✓ from music_assistant_client.exceptions import MusicAssistantError
Specific exceptions are found within the `exceptions` submodule.
This quickstart demonstrates how to connect to a Music Assistant server, retrieve server information, and list available music providers. Remember to replace `http://localhost:8095` with the actual URL of your Music Assistant instance.
import asyncio
from music_assistant_client import MusicAssistantClient
from music_assistant_client.exceptions import MusicAssistantError
async def main():
# Replace with your Music Assistant server URL (e.g., http://192.168.1.100:8095)
mass_client = MusicAssistantClient("http://localhost:8095")
try:
# Connect to the Music Assistant server
await mass_client.connect()
print(f"Connected to Music Assistant: {mass_client.server_info.server_version}")
# Example: List available music providers
providers = await mass_client.music.get_music_providers()
print("\nMusic Providers:")
for provider in providers:
print(f"- {provider.name} (type: {provider.type.value})")
# Example: Get all artists (might be large)
# artists = await mass_client.music.get_all_artists()
# print(f"\nTotal artists: {len(artists)}")
except MusicAssistantError as e:
print(f"Error connecting to Music Assistant: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
finally:
# Ensure the connection is properly closed
await mass_client.disconnect()
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingVersion 1.0.0 introduced a complete rewrite to a fully asynchronous client, requiring all API calls to be awaited. Code written for pre-1.0.0 synchronous versions will no longer work.fixRewrite client interaction to use `await` for all method calls and ensure the code runs within an `async` context (e.g., using `asyncio.run()`).
affects: <1.0.0 to 1.x.x
gotchaForgetting to `await` asynchronous method calls (e.g., `mass_client.connect()`) will lead to `TypeError` or `RuntimeWarning` exceptions, as the coroutine object is not executed.fixAlways prepend `await` to any call that returns a coroutine (e.g., `await mass_client.connect()`, `await mass_client.music.get_music_providers()`).
affects: All 1.x.x versions
gotchaThe client library requires an active Music Assistant server running and accessible at the specified URL. A `ConnectionRefusedError` (or similar) will occur if the server is offline or the URL/port is incorrect.fixVerify your Music Assistant server is running, check the specified URL and port, and ensure no firewalls are blocking the connection. The default port is 8095.
affects: All 1.x.x versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'music_assistant_client'
The `music-assistant-client` package is not installed in your current Python environment.
fixRun `pip install music-assistant-client` to install the library.
TypeError: object MusicAssistantClient can't be used in 'await' expression
You are trying to `await` the `MusicAssistantClient` *class* or an already connected instance, instead of its asynchronous methods (like `connect()`). This usually means you forgot `await` on a method call.
fixEnsure you are awaiting specific asynchronous methods, e.g., `await mass_client.connect()` or `await mass_client.music.get_all_artists()`.
aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host localhost:8095 ssl:False [Connection refused]
The Music Assistant server is not running, is inaccessible, or the specified host/port is incorrect. This is a network connection issue.
fixCheck if your Music Assistant server is running and reachable at the provided URL (e.g., `http://localhost:8095`). Verify the IP address and port, and check any firewall rules.
AttributeError: 'MusicAssistantClient' object has no attribute 'music'
You are attempting to access client features (like `mass_client.music`) before successfully establishing a connection to the Music Assistant server with `await mass_client.connect()`.
fixAlways call and `await` `mass_client.connect()` before attempting to use any other client methods.
Upgrade
Version history
1.3.5latest on PyPI · released Apr 10, 2026
Audit
Dependencies
aiohttprequiredRequired for making asynchronous HTTP requests to the Music Assistant server.
asyncio-throttlerequiredUsed internally for handling API rate limiting.