Getting Started

Spicetify is a multiplatform command-line tool to customize the official Spotify client.

Installation

Windows

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

winget install Spicetify.Spicetify

scoop install spicetify-cli

choco install spicetify-cli

See the Chocolatey package page for more details.

Spotify from Scoop

If you installed Spotify via Scoop, find its location and set it in your config:

$ scoop prefix spotify
C:\Users\<username>\scoop\apps\spotify\current

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

Linux

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

brew install spicetify-cli

yay -S spicetify-cli

For NixOS and Home Manager users, use the spicetify-nix flake. It provides declarative configuration and handles Spotify installation automatically.

Add the flake input:

{
  inputs.spicetify-nix.url = "github:Gerg-L/spicetify-nix";
}

Then import the module and configure:

# For Home Manager: spicetify-nix.homeManagerModules.spicetify

{ pkgs, inputs, ... }:
let
  spicePkgs = inputs.spicetify-nix.legacyPackages.${pkgs.system};
in {
  programs.spicetify = {
    enable = true;
    enabledExtensions = with spicePkgs.extensions; [
      adblockify
      hidePodcasts
      shuffle
    ];
    theme = spicePkgs.themes.catppuccin;
    colorScheme = "mocha";
  };
}

See the spicetify-nix documentation for full configuration options.

Linux-Specific Setup

Depending on how you installed Spotify, you may need additional configuration.

Adding Spicetify to PATH

If you installed Spicetify via a package manager (Homebrew, AUR, etc.) and the spicetify command isn’t found, you may need to add it to your PATH manually.

First, determine your shell:

echo $SHELL

Then add ~/.spicetify to your PATH based on your shell:

echo 'export PATH=$PATH:~/.spicetify' >> ~/.zshrc
source ~/.zshrc

echo 'export PATH=$PATH:~/.spicetify' >> ~/.bashrc
source ~/.bashrc

fish_add_path ~/.spicetify

Spotify from AUR

Grant write permissions to Spotify’s directory:

sudo chmod a+wr /opt/spotify
sudo chmod a+wr /opt/spotify/Apps -R

Spotify from spotify-launcher (Arch)

The spotify-launcher package installs Spotify to a user directory. Set the path in your config:

spicetify config spotify_path "$HOME/.local/share/spotify-launcher/install/usr/share/spotify"

Spotify from Snap

Snap apps cannot be modified. You’ll need to switch to the apt version:

Remove Snap Spotify:
Terminal window
```
snap remove spotify
```

Install via apt:

curl -sS https://download.spotify.com/debian/pubkey_C85668DF69375001.gpg | sudo gpg --dearmor --yes -o /etc/apt/trusted.gpg.d/spotify.gpg
echo "deb http://repository.spotify.com stable non-free" | sudo tee /etc/apt/sources.list.d/spotify.list
sudo apt-get update && sudo apt-get install spotify-client

Grant permissions:

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

Spotify from Flatpak

Find your Flatpak Spotify location:
Terminal window
```
flatpak --installations
```
Common locations:
- /var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify/
- ~/.local/share/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify/

Set the path:

spicetify config spotify_path "/var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify"

Find and set your prefs file (check both locations):

# Check which exists:
ls ~/.config/spotify/prefs
ls ~/.var/app/com.spotify.Client/config/spotify/prefs

# Set whichever exists (use the full absolute path):
spicetify config prefs_path /home/username/.var/app/com.spotify.Client/config/spotify/prefs

Grant permissions:

sudo chmod a+wr /var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify
sudo chmod a+wr -R /var/lib/flatpak/app/com.spotify.Client/x86_64/stable/active/files/extra/share/spotify/Apps

macOS

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

brew install spicetify-cli

After installing via Homebrew, set the Spotify path:

spicetify config spotify_path "/Applications/Spotify.app/Contents/Resources"

For nix-darwin and Home Manager users on macOS, use the spicetify-nix flake:

{
  inputs.spicetify-nix.url = "github:Gerg-L/spicetify-nix";
}

Import the module (spicetify-nix.darwinModules.spicetify for nix-darwin or spicetify-nix.homeManagerModules.spicetify for Home Manager) and configure programs.spicetify. See the Linux Nix tab for a configuration example.

Before First Run

Marketplace

The Spicetify Marketplace gives you a tab in Spotify’s sidebar to browse and install themes, extensions, and snippets.

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

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

Basic Usage

After installing Spicetify and Marketplace, you can customize Spotify using themes and extensions from the Marketplace tab in Spotify’s sidebar.

Updating

Spotify updates periodically. After a Spotify update, you’ll need to re-apply Spicetify:

spicetify backup apply

If that doesn’t work, Spicetify itself may need an update:

spicetify update

If you updated Spicetify via a package manager (Homebrew, AUR, etc.) or the update command didn’t fully apply changes, run:

spicetify restore backup apply

If no Spicetify upgrade is available yet, the team is likely still working on compatibility with the new Spotify version.

Legacy Versions

If you need an older Spicetify version (e.g., for Spotify v1.1.56 or older):

$v="1.2.1"; Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/spicetify/cli/main/install.ps1" | Invoke-Expression

curl -fsSL https://raw.githubusercontent.com/spicetify/cli/main/install.sh -o /tmp/install.sh
sh /tmp/install.sh 1.2.1

Legacy resources:

Edit this page