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

Update Music Assistant Server by pulling the latest code from the dev branch, rebuilding the Python virtual environment with ./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 and 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. 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:

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

The repository root contains 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. Run the canonical setup script to recreate the virtual environment:

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

This script, located at 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:

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

Migration logic resides in 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.

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 validation logic as manual Docker deployments.

Verify the Update

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

# 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 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 for migration lock files. Remove stale locks in $HOME/.musicassistant/ if the process was interrupted, then restart:

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 to reinstall dependencies defined in pyproject.toml.
• Database migrations run automatically via 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 in 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 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.

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