Getting Started

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

Installation

Windows

PowerShell (Recommended)

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

Winget

winget install Spicetify.Spicetify

Scoop

scoop install spicetify-cli

Chocolatey

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

Shell Script (Recommended)

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

Homebrew

brew install spicetify-cli

AUR (Arch)

yay -S spicetify-cli

Nix / NixOS

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 NixOS: spicetify-nix.nixosModules.spicetify
# 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.

note

The module installs Spotify for you. Do not install pkgs.spotify separately.

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:

zsh

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

bash

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

fish

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"

warning

When setting config values, use the full absolute path (e.g., /home/username/...). The ~ shortcut works in shell commands but not in config values.

Spotify from Snap

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

1. Remove Snap Spotify:

   snap remove spotify

2. 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

3. Grant permissions:

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

Spotify from Flatpak

1. Find your Flatpak Spotify location:

   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/

2. Set the path:

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

3. 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

4. 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

Shell Script (Recommended)

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

Homebrew

brew install spicetify-cli

After installing via Homebrew, set the Spotify path:

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

Nix / nix-darwin

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

tip

If this is a fresh Spotify install, open Spotify and log in for at least 60 seconds before running Spicetify. This allows Spotify to generate the files that Spicetify needs to function.

---

Marketplace

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

Windows

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

Linux / macOS

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):

Windows

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

Linux / macOS

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

Legacy resources:

• Spicetify v1 source (legacy branch)
• Legacy themes