# How to Set Up Music Assistant Server Locally: Complete Developer Guide

> Set up Music Assistant server locally with this developer guide. Install dependencies, clone the repository, configure and start your server easily for a personalized music experience.

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

---

**To set up Music Assistant server locally, install ffmpeg 6.1+ and Python 3.14, clone the music-assistant/server repository, execute [`scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/scripts/setup.sh) to configure a virtual environment, and start the server with `python -m music_assistant`.**

Music Assistant Server is an asynchronous Python service that manages your music library, integrates with streaming providers, and streams audio to various players. When you set up Music Assistant server locally for development, you gain direct access to the modular provider system and the async core engine defined in the open-source repository.

## Prerequisites for Local Development

Before you can set up Music Assistant server locally, ensure your system meets these requirements:

- **ffmpeg 6.1 or newer**: Required for audio processing and must be available on your `$PATH`. The server invokes ffmpeg directly through [`music_assistant/helpers/ffmpeg.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/ffmpeg.py).
- **Python 3.14**: The exact version is pinned in the repository's `.python-version` file and enforced during setup.
- **Git**: To clone the source repository.

## Installing from Source

The recommended method to set up Music Assistant server locally uses the provided setup script to automate virtual environment creation and dependency installation.

### Clone the Repository

Start by cloning the official repository:

```bash
git clone https://github.com/music-assistant/server.git
cd server

```

### Run the Setup Script

Execute the development setup script from the repository root:

```bash
scripts/setup.sh

```

This script performs several critical tasks:

- Creates a Python virtual environment in `.venv` (or reuses an existing one)
- Installs the project in editable mode (`pip install -e .`)
- Configures pre-commit hooks for code quality

The editable installation ensures that modifications to source files in `music_assistant/` are reflected immediately without reinstallation.

## Starting the Server

Once the environment is configured, activate the virtual environment and launch the server:

```bash
source .venv/bin/activate
python -m music_assistant --log-level debug

```

The entry point [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) initializes the core orchestrator in [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py), which starts the async event loop and loads configured providers. By default, the web interface is available at **http://localhost:8095**.

For VS Code users, press **F5** to launch the debugger with the same configuration defined in the repository's launch settings.

## Understanding the Core Architecture

When you set up Music Assistant server locally, you interact with several architectural layers defined in the source:

- **Core Engine** ([`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py)): Manages the async event loop and application lifecycle.
- **Providers** (`music_assistant/providers/`): Modular plugins for music sources (Spotify, local files) and player devices.
- **Controllers** (`music_assistant/controllers/`): Handle HTTP/WebSocket APIs (`webserver`), background tasks, and player orchestration.
- **Helpers** (`music_assistant/helpers/`): Utility modules including FFmpeg wrappers ([`ffmpeg.py`](https://github.com/music-assistant/server/blob/main/ffmpeg.py)) and SQLite database access ([`database.py`](https://github.com/music-assistant/server/blob/main/database.py)).

The server stores library metadata in `$HOME/.musicassistant/library.db`, managed by [`music_assistant/helpers/database.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/database.py).

## Docker Alternative for Local Testing

If you prefer not to install Python dependencies locally, you can run a containerized instance:

```bash
docker run -p 8095:8095 \
  -v $HOME/.musicassistant:/data \
  ghcr.io/music-assistant/server:latest

```

This image includes ffmpeg and exposes the same port 8095. However, for active development and debugging, the local Python setup provides faster iteration cycles.

## Summary

- **Install dependencies**: ffmpeg ≥6.1 and Python 3.14 must be present on your system before you set up Music Assistant server locally.
- **Automated setup**: Run [`scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/scripts/setup.sh) to create the virtual environment and install editable dependencies.
- **Launch command**: Use `python -m music_assistant --log-level debug` to start the async server and access the UI at localhost:8095.
- **Entry points**: The server boots via [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) and orchestrates components through [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py).
- **Storage**: Local library data persists in `$HOME/.musicassistant/library.db`.

## Frequently Asked Questions

### What Python version is required to run Music Assistant server locally?

Music Assistant server requires **Python 3.14** exactly, as specified in the repository's `.python-version` file. The [`scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/scripts/setup.sh) enforces this version when creating the virtual environment, ensuring compatibility with the async core and type annotations used throughout [`music_assistant/mass.py`](https://github.com/music-assistant/server/blob/main/music_assistant/mass.py) and related modules.

### Why does the server require ffmpeg?

The server relies on **ffmpeg 6.1 or newer** for audio transcoding, metadata extraction, and stream processing. The helper module [`music_assistant/helpers/ffmpeg.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/ffmpeg.py) spawns ffmpeg processes directly to handle audio pipelines, making the binary a hard dependency for both local development and Docker deployments.

### How do I reset the local database during development?

Delete the SQLite database file at `$HOME/.musicassistant/library.db` and restart the server. The [`music_assistant/helpers/database.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/database.py) module automatically recreates the schema on startup. For a complete reset, remove the entire `$HOME/.musicassistant/` directory, which also clears cached provider credentials and temporary audio files.

### Can I run Music Assistant server without Docker for production use?

While the Docker image (`ghcr.io/music-assistant/server:latest`) is recommended for production stability, you can run the server locally using the Python virtual environment method described above. Ensure ffmpeg remains on your `$PATH` and consider using a process manager like systemd or supervisor to handle the `python -m music_assistant` process in production environments.