Music Assistant Server Dependencies: Complete Build and Runtime Requirements

Music Assistant Server requires Python 3.14+, setuptools>=61 for building, and 35+ runtime dependencies including aiohttp, torch, and uv, all declared in pyproject.toml.

Music Assistant Server is a modern Python 3.14+ application that manages and streams music across your home network. The project uses PEP 621 metadata standards to declare all build and runtime requirements centrally in pyproject.toml, making dependency resolution straightforward and reproducible.

Build System Requirements

The minimal build-time dependencies are defined under the [build-system] section of pyproject.toml. According to the source code, you only need setuptools>=61 to create a distributable package from the repository.

Runtime Dependencies Overview

The complete list of runtime requirements is declared under project.dependencies in pyproject.toml (lines 11-50). These 35+ packages span networking, audio processing, cryptography, and data serialization.

Networking and HTTP Stack

Music Assistant relies heavily on asynchronous networking libraries:

• aiohttp (==3.14.0): The core async HTTP client/server powering the web interface and API endpoints.
• aiodns (>=3.2.0): Asynchronous DNS resolution, which pins pycares to version 4.11.0.
• aiohttp-asyncmdnsresolver (==0.1.1): mDNS resolver integration for aiohttp.
• aiohttp-fast-zlib (==0.3.0): Accelerated gzip/deflate handling.
• aiohttp-socks (==0.11.0): SOCKS proxy support for network connections.
• zeroconf (==0.149.12): Service discovery via mDNS/Bonjour.
• ifaddr (==0.2.0): Network interface discovery.

Database and File I/O

• aiosqlite (==0.22.1): Async SQLite driver for the local metadata database.
• aiofiles (==24.1.0): Asynchronous file operations.
• propcache (>=0.2.1): Property-caching helper used by the storage layer.

Audio Processing and Machine Learning

The server includes audio analysis capabilities requiring scientific Python libraries:

• torch (==2.11.0): PyTorch CPU-only wheel for neural network operations.
• torchaudio (==2.11.0): Audio support for PyTorch.
• librosa (==0.11.0): Audio analysis and feature extraction.
• numpy (==2.3.5): Numerical computing, pinned for CPU compatibility.
• mutagen (==1.47.0): Media file metadata extraction.

Security and Cryptography

• cryptography (==46.0.7): Encryption primitives for secure connections.
• certifi (==2025.11.12): CA bundle for TLS verification.
• pyjwt[crypto] (>=2.10.1): JSON Web Token handling with cryptographic support.

Data Serialization and Utilities

• orjson (==3.11.6): Ultra-fast JSON serialization for API responses.
• mashumaro (==3.20): Fast (de)serialization of data models.
• music-assistant-models (==1.1.132): Core data models for the application.
• music-assistant-frontend (==2.17.189): Web UI assets.
• awesomeversion (>=24.6.0): Version handling utilities.
• python-slugify (==8.0.4): URL-friendly slug generation.
• unidecode (==1.4.0): Unicode transliteration.
• shortuuid (==1.0.13): Compact UUID generation.
• xmltodict (==1.0.4): XML to dictionary conversion.
• chardet (>=5.2.0): Character encoding detection.

Additional Features

• aiortc (>=1.6.0): WebRTC implementation for real-time audio streaming.
• gql[all] (==4.0.0): GraphQL client for external service integration.
• podcastparser (==0.6.11): RSS feed parsing for podcast support.
• modern_colorthief (==0.2.1): Album art color extraction.
• pillow (==12.2.0): Image manipulation for artwork handling.
• getmac (==0.9.5): MAC address lookup for device identification.
• colorlog (==6.10.1): Colored terminal log output.
• Brotli (>=1.0.9): HTTP compression support.

Installation Methods

You can install the server using either uv (recommended) or classic pip.

Using uv (Recommended)

The project recommends uv (>=0.8.0) for fast, deterministic builds:

# Create a fresh virtual environment

python -m venv .venv && source .venv/bin/activate

# Install build-time tools

uv pip install --upgrade pip setuptools

# Install the Music Assistant server and all runtime dependencies

uv pip install -e .

Using pip

Alternatively, use standard pip:

pip install -e .

Both methods resolve the exact version constraints specified in pyproject.toml, ensuring reproducible builds across environments.

Key Source Files

Understanding the dependency structure requires examining these specific files in the music-assistant/server repository:

• pyproject.toml: Central declaration of all runtime and build dependencies (lines 11-50).
• music_assistant/__main__.py: Entry point that launches the mass CLI command.
• music_assistant/helpers/: Utility modules for networking, database, and logging that consume these dependencies.
• music_assistant/providers/: Plugin system where individual providers may declare additional optional dependencies.

Running the Server

After installation, the entry point is available as the mass command:

# Start the server with debug logging

mass --log-level debug

Summary

• Music Assistant Server requires Python 3.14+ and setuptools>=61 for building.
• Runtime dependencies are declared in pyproject.toml using PEP 621 metadata standards.
• Key categories include aiohttp for networking, torch/librosa for audio analysis, and aiosqlite for database operations.
• The recommended installation uses uv for faster, deterministic dependency resolution.
• The entry point mass is defined in music_assistant/__main__.py.

Frequently Asked Questions

What Python version is required to build Music Assistant Server?

Music Assistant Server requires Python 3.14 or newer. This version requirement ensures compatibility with the modern async libraries and type hints used throughout the codebase.

Can I install Music Assistant Server without using uv?

Yes, while uv (>=0.8.0) is recommended for faster installs and better dependency resolution, you can use standard pip install -e . after installing the build dependencies (setuptools>=61). Both methods read the same pyproject.toml file to resolve the exact version constraints.

Where are the dependencies declared in the source code?

All dependencies are declared in the pyproject.toml file at the repository root. Specifically, lines 11-50 contain the complete enumeration of runtime requirements under the project.dependencies section, while the [build-system] section specifies setuptools as the build backend.

Does Music Assistant Server have optional dependencies?

Yes, the provider system in music_assistant/providers/ may require additional optional dependencies. For example, the sonic analysis provider requires torch and librosa, which are included in the main dependency list but are only loaded when that specific functionality is enabled. The test suite also requires additional dependencies specified under project.optional-dependencies.test.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}