# How to Install Music Assistant Server Locally: Docker, Add-on, or Dev Setup

> Install Music Assistant server locally using Docker, a Home Assistant add-on, or a dev setup. Follow our guide for a seamless local music streaming experience.

- Repository: [Music Assistant/server](https://github.com/music-assistant/server)
- Tags: how-to-guide
- Published: 2026-06-18

---

**Install Music Assistant server locally by deploying the official Docker container, installing it as a Home Assistant add-on, or cloning the repository and running [`scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/scripts/setup.sh) to create a Python virtual environment, ensuring FFmpeg 6.1+ and Python 3.14+ are available first.**

Music Assistant is an asynchronous Python music library server that unifies streaming providers and speaker platforms. While the codebase can operate as a complete standalone product, it is tailored for side-by-side operation with Home Assistant, making the Home Assistant add-on the recommended installation method according to the [`README.md`](https://github.com/music-assistant/server/blob/main/README.md). This guide details the three supported pathways to run the music-assistant/server on your local machine.

## Prerequisites for Local Installation

Before installing Music Assistant server locally, verify your system meets the runtime dependencies specified in the repository documentation.

### Required System Components

- **FFmpeg** version 6.1 or higher (version 7 recommended). The server invokes FFmpeg for audio processing, and the binary must be available on your system `PATH` as noted in [`DEVELOPMENT.md`](https://github.com/music-assistant/server/blob/main/DEVELOPMENT.md).
- **Python 3.14+** if running from source. The project pins to this runtime version (referenced in `.python-version` and the `Dockerfile` which uses `python:3.14-slim-bullseye` as its base image).
- **Docker** engine installed and running for containerized deployments.

## Installation Methods

The music-assistant/server repository supports three distinct installation pathways, each suited to different use cases.

### Docker Container (Recommended for Standalone Servers)

The simplest method to install Music Assistant server locally is pulling the pre-built image from the GitHub Container Registry. The `Dockerfile` uses a slim Python 3.14 base image and bundles all OS dependencies, including FFmpeg binaries and vendored libraries.

Run the following command to start the server:

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

```

This command exposes the web interface on port **8095** and mounts a persistent data volume at `$HOME/.musicassistant` (mapped to `/data` inside the container). The [`docker-compose.yml`](https://github.com/music-assistant/server/blob/main/docker-compose.yml) file in the repository root provides an alternative orchestration template for Docker Compose users.

### Home Assistant Add-on (Recommended Method)

For installations integrated with Home Assistant, deploy Music Assistant as a supervised add-on. This method runs the same Docker image internally but exposes configuration through the Home Assistant UI, aligning with the project's design for home automation.

1. Open Home Assistant and navigate to **Settings** > **Add-ons** > **Add-on Store**.
2. Search for "Music Assistant" and click **Install**.
3. Configure the add-on options (network port, data path) and click **Start**.

The add-on manages the container lifecycle automatically, storing configuration in the Home Assistant data directory.

### Development Setup from Source (For Contributors)

To modify the codebase or run bleeding-edge changes, clone the repository and execute the automated setup script. The [`scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/scripts/setup.sh) bash script creates a Python virtual environment in `.venv`, installs all Python dependencies (including the vendored `msclap` binaries), and configures pre-commit hooks.

```bash
git clone -b dev https://github.com/music-assistant/server.git
cd server
scripts/setup.sh
source .venv/bin/activate

```

After activation, start the server directly from the `music_assistant` package:

```bash
python -m music_assistant --log-level debug

```

This entry point is defined in [`music_assistant/__init__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__init__.py) and initializes the async server core. The development workflow is documented in [`DEVELOPMENT.md`](https://github.com/music-assistant/server/blob/main/DEVELOPMENT.md), which specifies that FFmpeg must be manually installed on your host system when using this method.

## Verifying Your Local Installation

After starting the server via any method, verify functionality:

1. Open a browser and navigate to `http://localhost:8095` (or your configured host port).
2. The Music Assistant dashboard should load, prompting for initial provider configuration.
3. Check the log file at `$HOME/.musicassistant/musicassistant.log` (or the container logs via `docker logs music-assistant`) for startup errors.

If the interface loads without FFmpeg errors in the logs, your local installation is operational.

## Summary

- **Docker deployment** is the fastest production-ready method for standalone use, using the official `ghcr.io/music-assistant/server:latest` image based on `python:3.14-slim-bullseye` with port `8095` and volume `$HOME/.musicassistant:/data`.
- **Home Assistant add-on** is the recommended installation method per the [`README.md`](https://github.com/music-assistant/server/blob/main/README.md), providing native integration for existing HA installations through the Supervisor interface.
- **Development setup** requires cloning the repository and running [`scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/scripts/setup.sh) to establish a Python 3.14 virtual environment, suitable for code contributions and debugging.
- All methods require **FFmpeg 6.1+** on the host or inside the container, and the server cannot run as a standalone PyPI package due to binary dependencies on external OS components.

## Frequently Asked Questions

### Can I install Music Assistant server without using Docker?

No. According to the [`README.md`](https://github.com/music-assistant/server/blob/main/README.md) in the music-assistant/server repository, the application has "multiple dependencies on external/OS components such as FFmpeg and custom binaries," making it impossible to run as a standalone PyPI package. You must use either the Docker container, the Home Assistant add-on (which uses Docker internally), or the development setup which still requires manual installation of FFmpeg and other system libraries.

### What FFmpeg version is required for Music Assistant server?

Music Assistant server requires **FFmpeg version 6.1 or higher**, though version 7 is recommended for optimal performance and codec support. This requirement is enforced because the server uses FFmpeg for audio transcoding and stream processing. When running the Docker container, FFmpeg is bundled inside the image; for development setups, you must install it manually on your host system as specified in [`DEVELOPMENT.md`](https://github.com/music-assistant/server/blob/main/DEVELOPMENT.md).

### Where does Music Assistant store configuration data locally?

By default, Music Assistant stores all configuration, library databases, and cache in the `$HOME/.musicassistant` directory on the host machine. When using Docker, this path is mounted to `/data` inside the container via the `-v $HOME/.musicassistant:/data` volume flag. For Home Assistant add-on installations, the data resides within the Home Assistant configuration directory structure.

### How do I access the Music Assistant web interface after installation?

Once the server is running, access the web interface by navigating to `http://localhost:8095` in your browser, replacing `localhost` with your machine's IP address if accessing remotely. Port 8095 is the default exposed port defined in the `Dockerfile` and documentation. If you mapped a different host port during Docker deployment (e.g., `-p 8123:8095`), use that host port instead.