Installing mp3rgain

Updated 2026-11-11 · mp3rgain v3.16.2

Every supported channel for the CLI (mp3rgain) and the desktop GUI (mp3rgui), with the matching uninstall command and a quick check that it works. Release builds cover x86_64 and ARM64 on macOS (one universal binary), Linux, and Windows.

CLI or GUI?

Both use the same library code. Pick by workflow:

• mp3rgain (CLI): scripting, cron jobs, containers, CI, large library sweeps with -R. This is the mp3gain drop-in.
• mp3rgui (GUI): drag and drop, one-off albums, checking stored ReplayGain tags before you change anything.

Their defaults differ. The GUI turns on clipping prevention (-k) and mtime preservation (-p) and treats each folder as one album, while CLI -a treats every file given as one album. Installing both is fine; they are separate packages and do not conflict. The GUI is not on crates.io, MacPorts, Nix, pkgx, Termux, or Docker.

CLI: mp3rgain

Every GitHub release also carries plain archives: a macOS universal .tar.gz, Linux x86_64 and arm64 .tar.gz, Windows x86_64 and arm64 .zip, and .deb packages for amd64 and arm64, which also make up the apt repository. The macOS CLI binary is not signed or notarized; if macOS blocks a copy you downloaded in a browser, run xattr -d com.apple.quarantine ./mp3rgain.

Since v3.11.1 the Linux CLI binaries are statically linked, so they run on any distribution, old or new, glibc or not. https://github.com/M-Igashi/mp3rgain/releases/latest/download/mp3rgain-linux-x86_64.tar.gz (or -arm64) always fetches the current release.

GUI: mp3rgui

• macOS: the app (DMG or Homebrew cask) is signed with a Developer ID and notarized by Apple since v3.9.0. It needs macOS 11 or later.
• Windows: winget installs the GUI as a portable binary. For a Start Menu entry and an uninstaller, use the installer. Neither is code-signed.
• Linux: the GUI .deb packages and tarballs are built on Ubuntu 24.04 and need GTK 3, so use Ubuntu 24.04+ or Debian 13 (trixie)+. The AUR package mp3rgui builds from source and is maintained in this project; the CLI's mp3rgain-bin is a third-party package.

Debian and Ubuntu: apt repository

Every release is also published as a signed apt repository for amd64 and arm64, so both packages install with apt and update with apt upgrade. mp3rgain needs Debian 12 or Ubuntu 22.04 or later; mp3rgui needs Debian 13 or Ubuntu 24.04 or later (GTK 3). Add the repository once:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSLo /etc/apt/keyrings/mp3rgain.gpg https://github.com/M-Igashi/mp3rgain/releases/latest/download/mp3rgain-archive-keyring.gpg
echo "deb [signed-by=/etc/apt/keyrings/mp3rgain.gpg] https://github.com/M-Igashi/mp3rgain/releases/latest/download/ ./" | sudo tee /etc/apt/sources.list.d/mp3rgain.list
sudo apt update
sudo apt install mp3rgain     # and/or mp3rgui

The signing key's fingerprint is 54E7 BDDA 7581 ED3A 9689 0E9D 1697 D52D 7E5A 289D. The repository lives in the assets of the latest GitHub release, so it needs no server of its own; for a few minutes after a new release is published, apt update may report that it has no Release file, and the next update succeeds. To remove it again: sudo rm /etc/apt/sources.list.d/mp3rgain.list /etc/apt/keyrings/mp3rgain.gpg. A single .deb from GitHub Releases can still be installed by hand with sudo apt install ./mp3rgain_*_amd64.deb, but then it never updates.

Moving from the Ubuntu PPA

The PPAs ppa:m-igashi/mp3rgain and ppa:m-igashi/mp3rgui are deprecated: they keep receiving updates until 2026-12-31 and stop after that. The apt repository covers Ubuntu 26.04 too, and for the same version its packages take precedence over the PPA's, so adding it as above is all it takes; the next apt upgrade switches over. Then remove the PPA:

sudo add-apt-repository --remove ppa:m-igashi/mp3rgain
sudo add-apt-repository --remove ppa:m-igashi/mp3rgui   # if you installed the GUI

Verify the install

Confirm the binary runs and reports the version you expect before pointing it at a library:

mp3rgain -v
# mp3rgain version 3.16.2

mp3rgain song.mp3        # read-only: prints file info, changes nothing

Running mp3rgain on a file with no flags never writes, so it is the safest way to check that decoding works on your files. Add -n to preview any real operation.

Release artifact checksums

Release archives, .deb packages, the DMG, and the Windows installer each have a matching .sha256 file (the Linux GUI tarballs since v3.10.0). To verify a manual download:

curl -sLO https://github.com/M-Igashi/mp3rgain/releases/download/v3.16.2/mp3rgain-v3.16.2-windows-x86_64.zip
curl -sL  https://github.com/M-Igashi/mp3rgain/releases/download/v3.16.2/mp3rgain-v3.16.2-windows-x86_64.zip.sha256
sha256sum mp3rgain-v3.16.2-windows-x86_64.zip   # compare the two

Build provenance

Since v3.16.0 the same files also carry a GitHub build provenance attestation. With the GitHub CLI you can check that a download was built by this repository's release workflow from its tag, not just that it matches a checksum:

gh attestation verify mp3rgain-v3.16.2-windows-x86_64.zip --repo M-Igashi/mp3rgain

Docker

Multi-arch images (linux/amd64, linux/arm64) are published to GHCR for the CLI. The image is FROM scratch around a static musl binary: about 2 MB, no shell, no runtime dependencies. The binary is the entrypoint, so every CLI flag works unchanged:

docker run --rm \
  --user "$(id -u):$(id -g)" \
  -v /path/to/music:/music \
  ghcr.io/m-igashi/mp3rgain:latest -r -R /music

mp3rgain writes each changed file as a new file and renames it into place, so passing --user keeps rewritten files owned by you rather than root. Available tags: latest, v3.16.2, and v3 (floating major).

Troubleshooting

Windows Defender or SmartScreen flags mp3rgui.exe

Defender's cloud heuristics occasionally flag the GUI binary, and SmartScreen warns about unsigned programs (no Windows binary is code-signed). The binaries are built on public GitHub Actions runners from the tagged source, the build logs are open, and each asset can be checked with gh attestation verify. If you hit a detection, check the release asset on VirusTotal or report it to Microsoft as a false positive.

The Windows download is blocked or does not start

https://mp3rgain.tyna.ninja/download/windows redirects to the installer on GitHub Releases, so a network that blocks github.com blocks the download too. Because the installer is not code-signed, a browser may hold it back as an uncommon download; choose to keep the file. The same file, with its checksum, is listed on the latest release page, and winget install M-Igashi.mp3rgui installs the app without a browser.

mp3rgui does not open (OpenGL)

On macOS and Linux the GUI draws with OpenGL 2.0 or newer. Windows uses Direct3D 12 or Vulkan, falling back to a software renderer, so it usually starts in VMs and RDP sessions too; set MP3RGUI_RENDERER=glow to use OpenGL instead. If no renderer works, mp3rgui shows a dialog explaining why. The CLI needs no graphics at all.

cargo install fails or installs nothing

Building from source needs Rust 1.85 or newer; install a current toolchain with rustup if your distribution's rustc is older. The mp3rgain binary also needs the default features, so do not pass --no-default-features.

Ubuntu: "package has no installation candidate"

The deprecated PPA only ever published for Ubuntu 26.04 LTS. Use the apt repository instead, which serves Ubuntu 22.04 and later (mp3rgui: 24.04 and later). On anything older, use the Docker image or cargo install.

Next