# How to Update Music Assistant Server: Complete Upgrade Guide for Docker and Manual Installations

> Easily update Music Assistant Server with our complete guide. Learn how to update using Docker or manual installations to get the latest features and improvements.

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

---

**Update Music Assistant Server by pulling the latest code from the dev branch, rebuilding the Python virtual environment with [`./scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/./scripts/setup.sh), applying database migrations via `python -m music_assistant --run-migrations`, and restarting the async event loop.**

Updating Music Assistant Server ensures you receive the latest streaming improvements, security patches, and provider integrations. Whether you run the core Python application manually or deploy via the official Docker image, the upgrade process preserves your existing library metadata and player configurations stored in `$HOME/.musicassistant/`. This guide covers the exact terminal commands and key source files like [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) and [`music_assistant/helpers/database.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/database.py) required for a seamless update.

## Pre-Update Requirements

Before starting the update process, verify that your system meets the **Python 3.14+** requirement specified in `.python-version` and [`pyproject.toml`](https://github.com/music-assistant/server/blob/main/pyproject.toml). Ensure you have terminal or SSH access to the host running the server, and create a backup of your `$HOME/.musicassistant/` directory to safeguard against rare migration failures.

## Method 1: Update Manual Installation

Manual installations require pulling source code and rebuilding the environment. This method applies when running the server directly from the GitHub repository.

### Pull Latest Source Code

Navigate to your cloned repository and switch to the dev branch, which contains the latest stable development code:

```bash
cd /path/to/music-assistant/server
git checkout dev
git pull origin dev

```

The repository root contains [`README.md`](https://github.com/music-assistant/server/blob/main/README.md) and configuration files that define the server architecture according to the Music Assistant source code.

### Rebuild the Virtual Environment

The server depends on specific async libraries declared in [`pyproject.toml`](https://github.com/music-assistant/server/blob/main/pyproject.toml). Run the canonical setup script to recreate the virtual environment:

```bash
rm -rf .venv
./scripts/setup.sh

```

This script, located at [`scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/scripts/setup.sh), automates virtual environment creation, dependency installation, and pre-commit hook configuration as implemented in the official repository.

### Apply Database Migrations

Schema changes between versions require database updates. Trigger migrations manually to surface errors before restarting:

```bash
source .venv/bin/activate
python -m music_assistant --run-migrations

```

Migration logic resides in [`music_assistant/helpers/database.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/database.py), which handles SQLite schema updates automatically during server startup.

## Method 2: Update Docker Deployment

For containerized deployments, pull the latest image from the GitHub Container Registry instead of rebuilding the Python environment manually.

```bash
docker pull ghcr.io/music-assistant/server:latest
docker compose down
docker compose up -d

```

The `Dockerfile` in the repository root defines the production image build process, ensuring consistent async runtime environments across updates.

## Method 3: Update Home Assistant Add-on

If running as a Home Assistant add-on, the update process requires no terminal access:

1. Open **Settings > Add-ons > Music Assistant**.
2. Click **Update** when available (this pulls the latest Docker image).
3. Click **Start** to restart the server.

The add-on uses the same `Dockerfile` and [`scripts/check_config_entries.py`](https://github.com/music-assistant/server/blob/main/scripts/check_config_entries.py) validation logic as manual Docker deployments.

## Verify the Update

After restarting, confirm the server launches correctly by monitoring logs:

```bash

# For manual/systemd installations

journalctl -u music-assistant -f

# For Docker installations

docker logs -f music-assistant-server

```

Successful startup logs will show the async event loop initializing in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py) and loading provider manifests. Access the web UI at `http://<host>:8095` to confirm connectivity.

## Troubleshooting Migration Failures

If the server fails to start after updating, check [`music_assistant/helpers/database.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/database.py) for migration lock files. Remove stale locks in `$HOME/.musicassistant/` if the process was interrupted, then restart:

```bash
rm $HOME/.musicassistant/.migration_lock
python -m music_assistant --run-migrations

```

## Summary

- **Source updates** require `git pull origin dev` to fetch the latest async core improvements.
- **Environment refreshes** use [`./scripts/setup.sh`](https://github.com/music-assistant/server/blob/main/./scripts/setup.sh) to reinstall dependencies defined in [`pyproject.toml`](https://github.com/music-assistant/server/blob/main/pyproject.toml).
- **Database migrations** run automatically via [`music_assistant/helpers/database.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/database.py) or manually with `--run-migrations`.
- **Docker deployments** update via `docker pull ghcr.io/music-assistant/server:latest` without manual virtual environment management.
- **Configuration persistence** ensures `$HOME/.musicassistant/` retains your library across all update methods.

## Frequently Asked Questions

### How do I check my current Music Assistant Server version?

Check the server logs on startup, which display the version hash parsed from [`pyproject.toml`](https://github.com/music-assistant/server/blob/main/pyproject.toml) in [`music_assistant/__main__.py`](https://github.com/music-assistant/server/blob/main/music_assistant/__main__.py). Alternatively, query the web UI settings panel, which retrieves version metadata from the running async core.

### Will updating Music Assistant Server delete my music library?

No. The update process only modifies application code and the virtual environment. Your music library, playlists, and player configurations remain intact in `$HOME/.musicassistant/`. Database migrations in [`music_assistant/helpers/database.py`](https://github.com/music-assistant/server/blob/main/music_assistant/helpers/database.py) only update schema structures, never user data.

### Can I downgrade Music Assistant Server after updating?

Downgrading requires restoring a backup of your `$HOME/.musicassistant/` directory created before the update. Newer database schemas may not be backward compatible with older server versions. Always backup before major updates when testing the dev branch.

### How often should I update Music Assistant Server?

Update frequency depends on your deployment type. Production environments should follow tagged releases, while the dev branch receives daily async improvements and provider fixes. Check the repository README for release cadence recommendations.