spicetify-autopatch

Keep Spicetify alive after every Spotify update — automatically.

Spotify updates itself silently. Every update overwrites the app resources and wipes the Spicetify patch, so your theme, Marketplace and extensions disappear until you remember to run spicetify backup apply again.

spicetify-autopatch installs a tiny background job that notices this and re-applies the patch for you. One command, no Node, no Python, no runtime to install — just the shell your OS already ships with.

Platform	Scheduler used	Reacts to
macOS	launchd user agent	file changes in Spotify's Apps folder + every 15 min + login
Linux	systemd user timer + path unit (cron fallback)	file changes in Spotify's Apps folder + every 15 min + login
Windows	Scheduled Task	every 15 min + logon

---

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Gildaciolopes/spicetify-autopatch/main/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/Gildaciolopes/spicetify-autopatch/main/install.ps1 | iex

That's it. The installer verifies your setup, registers the background job and runs the first check immediately.

Prerequisite: Spicetify must already be installed and applied once (spicetify backup apply). If it is not, the installer tells you and stops without changing anything.

---

How it works

Every run does the same three cheap steps:

1. Locate Spotify. Read spotify_path from Spicetify's own config-xpui.ini, so snap, flatpak, Homebrew and custom install locations all work without configuration.
2. Check the patch. A patched install has an extracted Apps/xpui/index.html that mentions spicetify; a vanilla one never does. On macOS and Windows the version Spicetify recorded when it patched is also compared against the version currently installed, so a stale folder left behind by an update is not mistaken for a healthy patch.
3. Repair if needed. If the patch is gone, run spicetify backup apply and verify the result.

If the patch is intact — which is the normal case — the run costs a few milliseconds and does nothing.

Safety properties

• No update loop. Re-applying modifies the watched folder, which fires the watcher again; the second run sees a healthy patch and exits.
• Bounded retries. If a re-apply does not fix things, it is retried at most 3 times for that particular Spotify state, then it waits until Spotify changes again. A broken setup can never spin forever.
• Single instance. An atomic lock directory prevents the timer and the file watcher from running at the same time.
• Self-limiting log. autopatch.log is trimmed once it passes 1 MB.
• Nothing runs as root. Everything lives in your user account.

---

Does it survive a reboot?

Yes, on all three platforms. Nothing is kept in memory — the job is registered in the scheduler's own on-disk store, and each platform re-arms it when you log in. Every platform also runs one check at that moment, so an update Spotify performed while the machine was off is repaired before you open the app.

Platform	What makes it persist	Check on login
macOS	plist in ~/Library/LaunchAgents, scanned by launchd at every login	RunAtLoad
Linux	systemctl --user enable symlinks the units into timers.target / paths.target	OnStartupSec=2min
Windows	task stored in the Task Scheduler database	AtLogOn + StartWhenAvailable

One honest caveat: this is per login, not per boot. If the machine is powered on but nobody logs in, nothing runs — but Spotify is not running either, so there is nothing to repair.

To confirm it is armed on macOS:

launchctl print "gui/$(id -u)/io.github.gildaciolopes.spicetify-autopatch" | grep -E 'state|runs'

On Linux:

systemctl --user status spicetify-autopatch.timer spicetify-autopatch.path

On Windows:

Get-ScheduledTask -TaskName spicetify-autopatch | Get-ScheduledTaskInfo

---

Resource usage

At rest: nothing. There is no daemon, no resident process and no tray icon. The watching is done by launchd, systemd or Task Scheduler — schedulers your OS is already running whether or not this project exists.

A normal check, measured on macOS with the patch intact:

0.05 real     0.01 user     0.03 sys
11534336      maximum resident set size   (~11 MB)
 1589584      peak memory footprint       (~1.6 MB)

Most of that 11 MB is shared pages of sh, sed and grep that are resident anyway because the rest of the system uses them; the incremental cost is the ~1.6 MB footprint. At one run every 15 minutes, that is a CPU duty cycle of 0.006%.

Only the repair path costs real work: when Spotify has actually updated, spicetify backup apply runs for roughly 40 seconds. That is the same command you would otherwise type by hand, and it happens a handful of times a month.

---

Usage

macOS / Linux

# current state, recent activity
sh ~/.spicetify-autopatch/autopatch.sh --status

# force a check right now, printing what it does
sh ~/.spicetify-autopatch/autopatch.sh --verbose

# full log
cat ~/.spicetify-autopatch/autopatch.log

If ~/.local/bin is on your PATH, the installer also links the worker there, so spicetify-autopatch --status works directly.

Windows

& "$env:LOCALAPPDATA\spicetify-autopatch\autopatch.ps1" -Status
& "$env:LOCALAPPDATA\spicetify-autopatch\autopatch.ps1" -Verbose
Get-Content "$env:LOCALAPPDATA\spicetify-autopatch\autopatch.log" -Tail 40

---

Configuration

The check interval defaults to 900 seconds (15 minutes).

# macOS / Linux
SPICETIFY_AUTOPATCH_INTERVAL=300 sh install.sh

# Windows
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Gildaciolopes/spicetify-autopatch/main/install.ps1))) -IntervalSeconds 300

On macOS and Linux the interval is only a safety net — the file watcher usually reacts within seconds of an update.

---

Uninstall

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Gildaciolopes/spicetify-autopatch/main/install.sh | sh -s -- --uninstall

# Windows
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Gildaciolopes/spicetify-autopatch/main/install.ps1))) -Uninstall

This removes the scheduled job and ~/.spicetify-autopatch. Your Spicetify installation, themes and extensions are left untouched.

---

Alternative: freeze Spotify instead

Spicetify can patch the Spotify binary so it never updates:

spicetify spotify-updates block     # spicetify restore backup apply afterwards

That also keeps your theme alive, but pins you to one Spotify build with no security fixes, and a server-side forced upgrade breaks it anyway. spicetify-autopatch lets Spotify update normally and repairs the patch after the fact.

---

Files installed

Path	Purpose
~/.spicetify-autopatch/autopatch.sh (autopatch.ps1 on Windows)	the worker
~/.spicetify-autopatch/config (config.json)	resolved path to the spicetify binary
~/.spicetify-autopatch/state (state.json)	retry bookkeeping
~/.spicetify-autopatch/autopatch.log	activity log
~/Library/LaunchAgents/io.github.gildaciolopes.spicetify-autopatch.plist	macOS agent
~/.config/systemd/user/spicetify-autopatch.{service,timer,path}	Linux units
Scheduled Task spicetify-autopatch	Windows job

On Windows everything lives under %LOCALAPPDATA%\spicetify-autopatch instead.

---

Troubleshooting

spicetify not found — install Spicetify first: https://spicetify.app/docs/getting-started

spicetify is not configured yet — run spicetify backup apply once by hand, then re-run the installer.

Nothing happens after an update — check the log. If it shows SKIP ... failed attempts, spicetify backup apply itself is failing; run it manually to see the real error. This usually means Spotify was installed from the Microsoft Store or the Mac App Store, which Spicetify cannot patch. Install Spotify from https://spotify.com instead.

Linux, timer never fires — confirm the user manager is running: systemctl --user status spicetify-autopatch.timer.

---

License

MIT — see LICENSE.