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

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 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.
• 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:

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

Run the Setup Script

Execute the development setup script from the repository root:

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:

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

The entry point music_assistant/__main__.py initializes the core orchestrator in 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): 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) and SQLite database access (database.py).

The server stores library metadata in $HOME/.musicassistant/library.db, managed by 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:

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 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 and orchestrates components through 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 enforces this version when creating the virtual environment, ensuring compatibility with the async core and type annotations used throughout 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 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 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.

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