# Music Assistant Server Dependencies: Complete Build and Runtime Requirements

> Discover Music Assistant Server dependencies for a smooth build and runtime. Explore Python 3.14+, setuptools, aiohttp, torch, uv, and more detailed in pyproject.toml.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: build-requirements
- Published: 2026-06-15

---

**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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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:

```bash

# 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:

```bash
pip install -e .

```

Both methods resolve the exact version constraints specified in [`pyproject.toml`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/pyproject.toml)**: Central declaration of all runtime and build dependencies (lines 11-50).
- **[`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/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:

```bash

# 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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`](https://github.com/music-assistant/server/blob/main/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`.