How to Install and Run Swing Music

Updated

Swing Music is a self-hosted music streaming server, and you can install it in three ways: a one-command script on Linux or Mac (Apple Silicon), Docker (Compose or CLI), or portable binaries for Linux, Windows, and Mac. The Docker route is the most predictable if you want your music and config to persist across restarts, since you explicitly map both directories.

Before you start

  • A machine to run the server on (your own computer, a home server, or a VPS).
  • Your music files in a folder you can point the app at.
  • For Docker: Docker and Docker Compose installed.
  • Decide where config should live so your settings survive upgrades.

Option 1: One-command install (Linux / Mac Apple Silicon)

Run:

curl -fsSL http://setup.swingmx.com | bash

This is the fastest path on the platforms it supports. It is not listed for Windows, so use Docker or a portable binary there.

Option 2: Docker Compose

Create a docker-compose.yml:

services:
  swingmusic:
    image: ghcr.io/swingmx/swingmusic:latest
    container_name: swingmusic
    ports:
      - "1970:1970"
    volumes:
      - /path/to/music:/music
      - /path/to/config:/config
    environment:
      - SWINGMUSIC_PORT=1970
      - SWINGMUSIC_DEVICE_NAME=Host name here
    restart: unless-stopped

Then run docker compose up -d.

What each part does:

Setting Purpose
ports: 1970:1970 Exposes the web UI on port 1970
/path/to/music:/music Your music library inside the container
/path/to/config:/config Persistent config so settings survive restarts
SWINGMUSIC_PORT Port the app listens on
SWINGMUSIC_DEVICE_NAME Name shown for this server
restart: unless-stopped Keeps it running after reboots

Replace /path/to/music and /path/to/config with real paths on your host.

Option 3: Docker CLI

If you prefer a single command over a Compose file:

docker run -d \
  --name swingmusic \
  -p 1970:1970 \
  -v /path/to/music:/music \
  -v /path/to/config:/config \
  -e SWINGMUSIC_PORT=1970 \
  -e SWINGMUSIC_DEVICE_NAME="Host name here" \
  --restart unless-stopped \
  ghcr.io/swingmx/swingmusic:latest

Option 4: Portable binaries

Download the portable binary for Linux, Windows, or Mac from the site and run it directly. This avoids Docker entirely, which is useful on a desktop where you just want to try it.

Verify it's running

Open http://localhost:1970 in a browser (or http://<server-ip>:1970 from another machine). You should see the Swing Music interface. If nothing loads, check that the container is up with docker ps and that the port isn't already in use.

Common snags

  • Empty library after install: the /music mount is wrong or points at a folder with no audio files. Fix the host path and restart.
  • Settings reset on restart: /config isn't mapped, so nothing persists.
  • Port conflict: change both the host side of ports and SWINGMUSIC_PORT if 1970 is taken.
  • Windows/Mac without Docker: use the portable binary instead of the one-command script.

Once it's running, you can browse by folder, album, or artist, and use features like fuzzy search, duplicate handling, collections, and listening stats.