SpotX-Bash patches the local Spotify desktop client on Linux and macOS. The README is the canonical command and option reference. This FAQ focuses on behavior, compatibility, and support questions.

Getting Started
Features and Limitations
Compatibility and Other Mods
Troubleshooting
Linux
Nix
macOS
Advanced and Legacy

Getting Started

What does SpotX-Bash do?

SpotX-Bash modifies files in the installed Spotify desktop client to block ads and enable supported client-side features. It does not modify your Spotify account or Spotify's servers.

The project supports Linux and macOS. For Windows, see SpotX.

How do I use it?

Install Spotify, then run SpotX-Bash using the command in the README. The README should be treated as the current command and option reference.

By default, SpotX-Bash applies its free-tier patches. Paid Premium subscribers should use -p / --premium.

Snap and Nix-managed installations use different workflows. See Snap and Nix.

Which Spotify versions are supported?

The latest supported Spotify version is shown at the top of the README. New Spotify releases may require a SpotX-Bash update before they can be patched reliably.

SpotX-Bash rejects clients older than 1.1.59.710. Historical support remains useful for compatible older systems, but current supported clients are recommended whenever possible.

What happens after Spotify updates?

Run SpotX-Bash again after Spotify is installed, reinstalled, or updated. A Spotify update replaces files that SpotX-Bash modified.

On Linux, updates normally come from the package or installation method you chose. On macOS, Spotify includes its own updater. SpotX-Bash can block that updater with -B / --blockupdates.

If a brand new Spotify version is newer than the version currently supported by SpotX-Bash, use a supported client until SpotX-Bash is updated. macOS users can use --installmac for the current supported build or --rollback for the previous supported build.

Features and Limitations

Does SpotX-Bash provide free Spotify Premium?

No. SpotX-Bash changes the desktop client, not your account entitlement. Server-side Premium features such as Premium audio quality and offline music downloads still require an eligible paid plan.

Can I use SpotX-Bash with a paid Premium account?

Yes. Use -p / --premium so SpotX-Bash skips modifications intended for free-tier accounts while retaining the applicable client-side patches.

Does SpotX-Bash provide lyrics?

Spotify provides lyrics to both Free and Premium users, but availability can vary by track, account, market, device, and licensing. SpotX-Bash cannot add lyrics that Spotify does not provide.

The -l / --lyricsbg option only changes the lyrics background color on supported client versions.

See Spotify's lyrics support page for current Spotify-side availability.

Why can I still get ads with Spotify Connect, AirPlay, or casting?

SpotX-Bash only modifies the local desktop client. When another device is actually playing the media, that playback is handled outside the patched desktop client. Controlling the remote device from the desktop app does not make the remote playback originate from the patched client.

Can SpotX-Bash change my account region or unlock regional features?

No. SpotX-Bash is not region-limited itself, but it cannot change your account country, subscription entitlement, server-side feature eligibility, or Spotify's regional restrictions.

Why is a particular feature not included?

The project focuses on ad blocking and selected features already present in Spotify's desktop client. General UI customization and unrelated modifications are outside its scope.

Feature patches also depend on what exists in each Spotify build. See the Spotify Desktop Client Version Timeline for some historical client changes.

Compatibility and Other Mods

Which platforms does SpotX-Bash support?

SpotX-Bash supports the Spotify desktop client on Linux and macOS.

SpotX-Bash's current Linux desktop path is built around the x86_64 Spotify client payload. Spotify's own Linux page provides Snap and Debian/Ubuntu installation methods and notes that Linux is not an actively supported platform in the same way as its Windows and Mac clients.

Spotify's current desktop system requirements list macOS 12 or later. SpotX-Bash also retains support for specific older Spotify clients that can run on older macOS releases. See legacy macOS compatibility.

Can SpotX-Bash and Spicetify be used together?

SpotX-Bash and Spicetify should not be used together. Both projects modify Spotify client files, and changes made by one can replace or interfere with changes made by the other. Combined installations are outside SpotX-Bash support.

If you ignore this warning and use both anyway, the order is:

Start with stock Spotify.
Apply SpotX-Bash.
Apply Spicetify.

Using that order does not make the combination supported.

If you are troubleshooting SpotX-Bash behavior, first restore Spotify from Spicetify's modifications:

spicetify restore

Spicetify documents restore as removing Spicetify modifications. That is the right way to remove Spicetify from a SpotX-Bash reproduction, but it is not a substitute for the full cleanup and reinstall needed to establish a fresh stock baseline. Reproduce the SpotX-Bash issue without applying Spicetify again.

Are there security or account concerns?

SpotX-Bash is an open source script intended to modify only the local Spotify client. Use the copy from the official repository and review the source if you have concerns.

On Linux, SpotX-Bash may request sudo when protected client files need to be updated. The Snap helper also uses sudo for package rebuild and installation operations.

SpotX-Bash cannot guarantee account safety. Ad blocking may conflict with Spotify's terms, so use the project at your own risk and review the terms that apply to your account and region.

Security issues in SpotX-Bash can be reported privately through the repository's security advisory form.

Troubleshooting

What counts as a valid fresh-stock test?

For a bug where Spotify behaves differently after SpotX-Bash is applied, a valid comparison uses the exact same Spotify version immediately before and after patching.

Use this sequence:

full automated cleanup
    |
fresh Spotify install
    |
test the issue on completely stock Spotify
    |
record the exact Spotify version and result
    |
apply SpotX-Bash and save its exact command/output
    |
test the exact same issue again
    |
confirm the exact same Spotify version is still installed

A valid stock test is the test performed after the full cleanup and fresh install, before SpotX-Bash is applied.

These do not establish a valid stock baseline:

Spotify worked stock sometime earlier.
The stock test used an older or different Spotify version.
Only --uninstall was run.
Only xpui.spa or another patched file was restored.
Old Spotify app or cache state was left in place instead of performing the full cleanup.
Spicetify was still applied during the SpotX-Bash reproduction.

Use the automated cleanup and complete workflow in the Troubleshooting guide. For a bug report, keep the cleanup transcript, exact Spotify version, written stock result, exact SpotX-Bash command/output, and written patched result.

Screenshots or a short recording can be useful for visual problems, but they are optional supplementary evidence and are not required for a valid stock comparison.

If SpotX-Bash fails before it can patch Spotify, such as during path detection or client installation, a stock-versus-patched comparison may not apply. The bug form allows N/A with an explanation in that case.

Why does SpotX-Bash say Spotify is not found?

SpotX-Bash searches several common Linux layouts and can also follow the installed spotify command and Flatpak metadata. If automatic discovery still fails, use -P <path> with the client root that contains both the spotify executable and Apps/xpui.spa.

Common Linux layouts include:

Installation type	Common client root or handling
Spotify Debian/Ubuntu package	`/usr/share/spotify`
`/opt` style packages, including common Arch/AUR layouts	`/opt/spotify`
spotify-launcher	`$HOME/.local/share/spotify-launcher/install/usr/share/spotify`
RPM Fusion style packaging	commonly under `/usr/share/spotify-client`
Negativo17 Fedora `spotify-client`	`/usr/lib64/spotify-client`
Flatpak	discovered from Flatpak metadata and the active `com.spotify.Client` files
Snap	use `spotx-snap.sh`, not normal `spotx.sh` or `-P`
NixOS or another Nix-managed installation	use SpotX-Nix rather than modifying `/nix/store`

RPM layouts are not universal. In particular, the Negativo17 Fedora package is intentionally supported separately from RPM layouts under /usr/share/spotify-client.

On macOS, -P should point to the directory containing Spotify.app. SpotX-Bash normally checks $HOME/Applications/Spotify.app and /Applications/Spotify.app automatically.

If Spicetify has been applied, run spicetify restore before deciding that SpotX-Bash cannot find an otherwise supported installation.

Why do I get cURL, DNS, or certificate errors?

Errors such as Failed to connect, Could not resolve host, or certificate verification failures usually indicate a network, DNS, proxy, TLS interception, certificate-store, or system date/time problem rather than a SpotX-Bash patching problem.

The normal official launcher is:

bash <(curl -sSL https://spotx-official.github.io/run.sh)

The script can also be fetched directly from the official GitHub repository:

bash <(curl -sSL https://raw.githubusercontent.com/SpotX-Official/SpotX-Bash/main/spotx.sh)

If one official source is unreachable, try the other. For certificate failures, verify the computer's date and time, check VPN/proxy/security software or TLS interception, and repair the local certificate problem. You can also download spotx.sh from the official repository and run the local file with Bash.

Do not disable TLS certificate verification as a normal workaround. Fix the certificate or network problem instead.

Why does the recommended command fail in my shell?

SpotX-Bash itself is a Bash script. However, in this command:

bash <(curl -sSL https://spotx-official.github.io/run.sh)

<(...) is process-substitution syntax parsed by your current shell before Bash starts. A login shell that does not support that syntax can reject the command even though SpotX-Bash itself runs under Bash.

A pipe form avoids process substitution:

curl -sSL https://spotx-official.github.io/run.sh | bash

When passing SpotX-Bash options through the pipe form, use bash -s -- before them:

curl -sSL https://spotx-official.github.io/run.sh | bash -s -- -cfh

Interactive mode and any automatically shown questions will work with the pipe command when it is run from a Terminal.

For unattended automation, add --noninteractive. This prevents all questions but does not automatically select any actions, so include options such as --installmac or --installdeb when needed.

Downloading spotx.sh and running bash spotx.sh [options] is another option. Your login shell does not need to be Bash as long as the invocation you use is valid in that shell and the SpotX-Bash script itself is run by Bash.

Where is the full troubleshooting procedure?

See the Troubleshooting guide. It defines the clean stock reproduction used by the bug-report form and includes the automated full cleanup command.

Linux

How should I install Spotify on Linux?

Spotify's Linux download page provides its Snap and Debian/Ubuntu methods. Other distributions may use community packaging such as Flatpak, RPM packages, AUR packages, or spotify-launcher.

For regular non-Snap installations, install a working stock Spotify client first and then run SpotX-Bash. SpotX-Bash can also install its Debian client source on APT-based systems with --installdeb; see the README for the current command reference.

If the unmodified client cannot install or run correctly on the system, fix that first before troubleshooting SpotX-Bash.

Is the Snap version of Spotify supported?

Yes, through the included spotx-snap.sh helper. A Snap is a read-only image, so the normal spotx.sh path does not patch the installed Snap in place.

Clone or download the repository so spotx-snap.sh and spotx.sh remain in the same directory, then run:

bash spotx-snap.sh

The helper uses or obtains a clean Spotify Snap, verifies official Snap metadata when possible, unpacks it, applies SpotX-Bash in build mode, repacks it, and installs the locally built Snap. A locally installed patched Snap does not receive normal automatic Snap Store updates.

To return to the official store-managed Spotify Snap:

bash spotx-snap.sh --restore

Run bash spotx-snap.sh --help for helper options such as --download, --snap-file, and --build-only. The README contains the current setup instructions. Options that do not apply to a Snap rebuild, including -P, --installmac, --installdeb, --rollback, and -c, are rejected by the helper.

Do not run spotx-snap.sh with bash <(curl ...); it needs the local spotx.sh file beside it.

Nix

How do I use SpotX-Bash with Nix?

Use SpotX-Nix. It applies SpotX-Bash while the Spotify package is being built and provides a separate spotify-spotx package rather than modifying files in the read-only Nix store.

SpotX-Nix supports x86_64 Linux and Apple Silicon macOS. It can be used with NixOS, nix-darwin, or Home Manager, with or without flakes. Follow the SpotX-Nix README for current configuration examples.

ARM Linux is not supported because Spotify does not provide an ARM Linux client. Intel macOS is not currently supported through SpotX-Nix because Nixpkgs does not package Spotify for Intel macOS. Intel macOS users can continue using regular SpotX-Bash outside Nix.

Do not point the normal SpotX-Bash command at an existing package inside /nix/store.

macOS

How do I install Spotify on macOS?

You can install Spotify normally from Spotify and then run SpotX-Bash.

On currently supported macOS releases, SpotX-Bash can also download and install the current SpotX-Bash-supported Spotify build before patching it:

bash <(curl -sSL https://spotx-official.github.io/run.sh) --installmac

To install the previous SpotX-Bash-supported build instead:

bash <(curl -sSL https://spotx-official.github.io/run.sh) --rollback

-V is no longer supported. Do not use old FAQ examples that pass a specific version with -V.

Apple Silicon users who manage applications through Nix can use SpotX-Nix instead.

What about older macOS versions?

Spotify's current desktop requirements list macOS 12 or later. SpotX-Bash retains compatibility logic for older Spotify clients on earlier systems:

macOS version	Maximum client handled by the current legacy compatibility logic
OS X 10.11 / macOS 10.12	`1.1.89.862`
macOS 10.13 / 10.14	`1.2.20.1218`
macOS 10.15	`1.2.37.701`
macOS 11	`1.2.66.447`

These are historical client compatibility limits, not Spotify's current supported-system requirements.

On these legacy macOS versions, current --installmac does not automatically install the historical maximum version. SpotX-Bash instead displays guidance for obtaining a compatible legacy client and exits. Install the compatible client first, then run SpotX-Bash against it.

SpotX-Bash itself requires OS X 10.11 or later. Spotify has also disabled sufficiently old desktop clients, so older operating systems cannot be kept working indefinitely by SpotX-Bash alone.

See the Spotify Desktop Client Version Timeline for historical version notes.

What does codesigning have to do with SpotX-Bash?

Modifying an application invalidates its original code signature. On macOS, SpotX-Bash clears Spotify's extended security attributes and, by default, applies an ad-hoc signature after patching. It then performs a strict deep signature verification before reporting success.

The codesign tool is required for the default path and is available with Apple's Xcode Command Line Tools. If it is missing, SpotX-Bash directs you to install the tools with:

xcode-select --install

-S / --skipcodesign skips the signing step, but it can leave a modified Spotify app that macOS refuses to launch depending on the system's security state. SpotX-Bash does not recommend disabling Gatekeeper or System Integrity Protection as a substitute for normal signing.

See SpotX-Bash and Code signing for additional background.

Advanced and Legacy

What is Developer Mode?

-d / --devmode enables supported developer features already present in the Spotify desktop client, including Chromium developer tooling and Spotify debugging controls when the installed version contains them.

These controls can change Spotify experiments and local behavior. Use them only if you understand what you are changing. Clearing Spotify's app cache can reset many local experiment changes.

SpotX-Bash's permanent Developer Mode support begins with Spotify 1.1.84.716. Availability of individual developer controls still varies by client version.

A separate temporary Developer Mode helper is available here.

What is the old UI option?

This is legacy functionality.

The -o / --oldui option applies only to the historical UI transition range supported by SpotX-Bash, from Spotify 1.1.93.896 through 1.2.13.661. Spotify removed the old UI from later clients, and SpotX-Bash warns that the option is unsupported after 1.2.13.661.

Use the Spotify Desktop Client Version Timeline if you need the historical context. Current users should not treat the old UI option as a normal feature of modern Spotify builds.