One script to fix Spicetify + Flatpak headaches. This script exists because fighting Spicetify + Flatpak can be a trial-and-error nightmare of broken paths, missing prefs, and permission quirks. The goal now is simple: you run one script, it does the annoying parts, and you end up with a customized Spotify + Marketplace.
If this saves you a couple of hours or some sanity, a ⭐ on GitHub is genuinely appreciated and helps keep the project polished!
- Automates Everything: Automatically detects your package manager, installs dependencies, downloads the official Spicetify installer, and patches the app.
- Smart Path Detection: Automatically finds where Flatpak hid your Spotify installation (user or system) and wires it into Spicetify.
- Fixes Permissions: Handles the annoyingly complex Flatpak permission issues automatically.
- Marketplace Ready: Hooks into the official installer and prompts you to install the Spicetify Marketplace.
- Safe to Re-run: Idempotent by design. If you run it multiple times, it won't trash your setup; it just updates or fixes things.
- Dry-Run Support: Test the script without making changes using
-n/--dry-run. - Uninstall Support: Remove Spicetify and restore Spotify to vanilla state with
-u/--uninstall.
Cross-distro compatible:
- Arch, Artix, EndeavourOS, Manjaro, Garuda (pacman)
- Debian, Ubuntu, Mint, Pop!_OS, Zorin, elementary, Kali (apt)
- Fedora, RHEL, CentOS, Rocky, Alma, Amazon Linux, Nobara (dnf/yum)
- openSUSE, SUSE (zypper)
- Alpine (apk)
- Gentoo (emerge)
- Void (xbps)
- Solus (eopkg)
- Clear Linux (swupd)
- NixOS (nix)
Shell support: bash, zsh, fish
You must have the Spotify Flatpak installed from Flathub and run it at least once. (The script will offer to install Flatpak for you if it isn't detected.)
flatpak install flathub com.spotify.Client
flatpak run com.spotify.Client # Open once to generate config files, then close it.- Clone the repository (or download the source zip from Releases)
git clone https://github.com/boudywho/easy-spicetify-arch.git
cd easy-spicetify-arch- Make executable and run
chmod +x spicetify-universal.sh
./spicetify-universal.sh(Note: During installation, type y when asked if you want to install the Spicetify Marketplace unless you explicitly don't want it. Once finished, restart Spotify to see your changes!)
| Option | Description |
|---|---|
-h, --help |
Show help message |
-d, --debug |
Enable debug mode (set -x) |
-n, --dry-run |
Show what would be done without executing |
-u, --uninstall |
Uninstall Spicetify and restore Spotify |
-v, --version |
Show version |
-V, --verbose |
Enable verbose output |
| Variable | Description |
|---|---|
DEBUG=1 |
Enable debug output |
DRY_RUN=1 |
Dry-run mode (no changes) |
VERBOSE=1 |
Enable verbose output |
SPICETIFY_INSTALL_URL= |
Override installer URL |
SPICETIFY_INSTALLER_SHA256= |
Expected SHA256 of installer |
Most issues fall into one of these buckets:
"Cannot detect Spotify prefs file" / prefs_path complaints
You must open Spotify at least once before running the script so it creates the necessary config files. Run
flatpak run com.spotify.Client, close it, and run the script again.
Permission Errors
The script attempts to fix these automatically (e.g., running
chmod -R a+wron the Flatpak Spotify directories). If Spicetify still complains about writing/patching, try running the script again.
Need Help?
If anything looks off or half-works, open an issue on GitHub. Please include your script version, your distro/DE, and the full script output.
You don't need this if you use the script. This is just the "what the script automates for you" section.
sudo pacman -S curl unzip --noconfirm # Or your distro's equivalentcurl -fsSL https://raw.githubusercontent.com/spicetify/cli/main/install.sh | shFollow the prompts, and make sure spicetify ends up in your PATH.
Spotify install path:
sudo flatpak info --show-location com.spotify.ClientThe spotify_path is usually <that_location>/files/extra/share/spotify or <that_location>/files/share/spotify.
Spotify prefs path:
Usually ~/.var/app/com.spotify.Client/config/spotify/prefs.
Let Spicetify know where Spotify and your prefs live:
spicetify config spotify_path /your/spotify/path
spicetify config prefs_path /your/prefs/pathReplace <Spotify App Files Path> with your actual path from step 3:
sudo chmod -R a+wr "<Spotify App Files Path>"spicetify restore
spicetify backup apply
spicetify apply