How to Install and Use Spicetify on Windows, Mac and Linux (2026 Guide)

Spicetify is a free command line tool that patches the Spotify desktop app so you can change its theme, add extensions, and install custom apps from a built in Marketplace. This guide covers the current install commands for Windows, Mac and Linux, what to run after every Spotify update, and fixes for the errors people hit most often, including “please manually set spotify path” and the Microsoft Store problem.

Last checked: August 2026, against Spicetify CLI 2.44 and the current Spotify desktop client. Commands below are the official ones from spicetify.app.

Before you install: three things that break Spicetify

1. Use the Spotify installer from spotify.com, not the Microsoft Store. The Store version is sandboxed and Spicetify cannot patch it. If you have the Store app, uninstall it completely, then download the desktop installer from spotify.com/download.
2. Open Spotify and stay logged in for at least a minute before you run Spicetify the first time. It needs the app to have written its prefs file.
3. Spicetify does not work on phones. It patches the desktop client only. There is no Spicetify for Android or iPhone, and any app claiming otherwise is not Spicetify.

How to install Spicetify on Windows

Open PowerShell as your normal user (not as Administrator) and run:

iwr -useb https://raw.githubusercontent.com/spicetify/cli/main/install.ps1 | iex

The script installs the CLI, adds it to your PATH, and asks whether you also want the Marketplace. Say yes; it saves a step later.

If you prefer a package manager, any of these works, but keep using the same one for updates:

winget install Spicetify.Spicetify
scoop install spicetify-cli
choco install spicetify-cli

Scoop users who also installed Spotify through Scoop need to point Spicetify at it once:

spicetify config spotify_path "C:\Users\<username>\scoop\apps\spotify\current"

How to install Spicetify on Mac

Open Terminal and run the official script:

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

Or use Homebrew:

brew install spicetify-cli
spicetify config spotify_path "/Applications/Spotify.app/Contents/Resources"

The second line is the part most Mac guides leave out. Homebrew does not know where Spotify lives, so without it you get the “please manually set spotify path” error on first run.

How to install Spicetify on Linux

The same curl script works on Linux:

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

Arch users can install from the AUR (yay -S spicetify-cli). If spicetify apply fails with a permission error, Spotify’s install folder is read only for your user. Fix it once:

sudo chmod a+wr /usr/share/spotify
sudo chmod a+wr /usr/share/spotify/Apps -R

Replace /usr/share/spotify with /opt/spotify if that is where your distro put it. Snap and Flatpak builds of Spotify need extra steps; the Spicetify docs cover those.

First run: the two commands you need

After installing, run these once, in this order:

spicetify backup apply

backup stores a clean copy of Spotify’s files so you can undo everything. apply patches Spotify and restarts it. If Spotify opens and looks identical, that is expected: you have not chosen a theme yet.

Then install the Marketplace if the installer did not already:

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.ps1 | iex

Mac and Linux

curl -fsSL https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.sh | sh

Restart Spotify and a Marketplace entry appears in the left sidebar.

How to use Spicetify Marketplace

Marketplace is where almost everyone should install things from. It has five tabs:

• Extensions: small add ons such as full screen mode, shuffle+, keyboard shortcuts, and lyrics.
• Themes: complete looks with colour schemes. Popular ones are Comfy, Dribbblish, Text, and Catppuccin.
• Snippets: one line CSS tweaks such as hiding the podcast shelf or rounding album art.
• Apps: custom pages that live in the sidebar, for example a stats dashboard or a lyrics page.
• Installed: everything you have added, with toggles to disable or remove.

Click Install on anything and Marketplace applies it without you touching the terminal. To change a theme’s colour scheme, open the theme card and pick from the dropdown.

Installing a theme manually

If a theme is not on Marketplace, clone or download it from GitHub, then copy its folder into your Spicetify Themes directory:

• Windows: %appdata%\spicetify\Themes\
• Mac and Linux: ~/.config/spicetify/Themes/

Then tell Spicetify to use it:

spicetify config current_theme ThemeFolderName
spicetify config color_scheme SchemeName
spicetify apply

color_scheme is optional; leave it out to use the theme’s default. If you are not sure where your config folder is, spicetify config-dir prints it.

What to do after Spotify updates

Spotify updates replace the files Spicetify patched, so your theme disappears. This is normal. Run:

spicetify backup apply

If that errors, use the full reset version:

spicetify restore backup apply

To stop doing this by hand, point your Spotify shortcut at spicetify auto instead of the Spotify executable. It checks, patches if needed, and launches Spotify in one go.

How to update Spicetify itself

spicetify update

If you installed with winget, scoop, choco, or Homebrew, update through that tool instead (brew upgrade spicetify-cli, scoop update spicetify-cli, and so on). Mixing methods is the most common way to end up with two copies fighting each other.

How to remove Spicetify

Restore Spotify to stock first, then delete the tool:

spicetify restore

Then uninstall the CLI the way you installed it (package manager uninstall, or delete the spicetify folder in %localappdata% on Windows or ~/.spicetify on Mac and Linux). Deleting the config folder listed above removes your themes and settings.

Troubleshooting

“please manually set spotify path”
Spicetify could not find the Spotify app. Set it explicitly. Typical locations:

• Windows: spicetify config spotify_path "C:\Users\<you>\AppData\Roaming\Spotify"
• Mac: spicetify config spotify_path "/Applications/Spotify.app/Contents/Resources"
• Linux: spicetify config spotify_path "/usr/share/spotify" or /opt/spotify

“cannot find pref_file” or “prefs_path” errors
Spotify has not created its prefs file yet. Open Spotify, log in, wait a minute, close it, and try again. If it still fails, set the path yourself: on Windows the file is C:\Users\<you>\AppData\Roaming\Spotify\prefs; on Mac it is ~/Library/Application Support/Spotify/prefs; on Linux run find ~ | grep "spotify/prefs$" to locate it, then spicetify config prefs_path "<full path>".

Where is config-xpui.ini?
%appdata%\spicetify\config-xpui.ini on Windows, ~/.config/spicetify/config-xpui.ini on Mac and Linux. You rarely need to edit it by hand; spicetify config key value writes to it for you.

“spicetify is not recognized” after installing
Close and reopen the terminal so the new PATH loads. On Windows, if it still fails, add %localappdata%\spicetify to your PATH manually.

Spotify opens but nothing changed
You ran apply without a theme selected, or Marketplace is not installed. Install Marketplace, pick a theme, and it takes effect immediately.

Marketplace tab is missing
Run the Marketplace install command for your OS again, then spicetify apply. If it is still missing, spicetify config custom_apps marketplace followed by spicetify apply registers it.

Songs will not play after a Spotify downgrade
Delete Spotify’s cache folder and restart: %LOCALAPPDATA%\Spotify on Windows, ~/Library/Application Support/Spotify on Mac, ~/.config/spotify on Linux.

Lyrics extension shows nothing
The extension relies on a Musixmatch token that gets rate limited. Open the extension’s settings inside Spotify and paste your own token from the Musixmatch app.

Is Spicetify safe, and will it get me banned?

Spicetify only changes the look and layout of the desktop app on your computer. It does not touch your account, does not bypass Premium, and does not modify audio playback. It has been publicly developed on GitHub since 2018 and we have not seen a credible report of an account action for using it. The main risk is third party themes or extensions from outside Marketplace, so stick to Marketplace unless you can read the code.

FAQ

Does Spicetify work with Spotify Free?
Yes. It patches the client, so Free and Premium accounts both work. It does not remove ads.

Can I use Spicetify on Android or iPhone?
No. It is desktop only (Windows, Mac, Linux).

Do I need to reinstall Spicetify when Spotify updates?
No. Run spicetify backup apply and your setup comes back.

Which Spotify version do I need?
The current desktop client from spotify.com. Spicetify tracks new Spotify releases within days; if apply fails right after a big Spotify update, run spicetify update first.

How do I make my own theme?
Copy an existing theme folder from the Themes directory, rename it, and edit its color.ini (colour schemes) and user.css (layout). The Spicetify docs have a theme development guide.

Read next: How to see your Spotify stats