# How to install Spicy Lyrics Spicy Lyrics replaces Spotify's standard lyrics view with animated lyrics, dynamic backgrounds, romanization, and customization options. It runs through **Spicetify**, a customization tool for the Spotify desktop app. :::info **Already have Spicetify and Marketplace installed?** Skip to [Install Spicy Lyrics](#3-install-spicy-lyrics). ::: ## What you'll need * The Spotify desktop app * An internet connection * About five minutes Spicy Lyrics is made for Spotify on desktop. It cannot be installed in the Spotify mobile app. ## 1. Install Spicetify If you already use Spicetify, skip to [Check for Marketplace](#2-check-for-marketplace). If you have only just installed Spotify, open it, sign in, and leave it running for at least 60 seconds before installing Spicetify. This allows Spotify to create the files Spicetify needs. ### Windows Open **PowerShell** and run: ```powershell iwr -useb https://raw.githubusercontent.com/spicetify/cli/main/install.ps1 | iex ``` Follow the instructions shown in PowerShell. ### macOS/Linux Open **Terminal** and run: ```bash curl -fsSL https://raw.githubusercontent.com/spicetify/cli/main/install.sh | sh ``` Some Linux installations require extra setup depending on how Spotify was installed. Snap installations of Spotify cannot be modified by Spicetify. For operating-system-specific help, see the [official Spicetify installation guide](https://spicetify.app/docs/getting-started). ![A successful Spicetify installation in the Windows Terminal](https://guides.spicylyrics.org/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzFhNjFjY2M5LTM4MWYtNGE5MS1iYWJjLTlhYjMyZDJiOGNjOC9lZWJhMDEwYi1jYmUwLTQzNWMtYjc1Ni1iY2ZkNDRhNjA0MGMvMDEtc3BpY2V0aWZ5LWluc3RhbGxlZC5wbmciLCJ0eXBlIjoiYXR0YWNobWVudCIsImlhdCI6MTc5MTU1OTgwMCwiZXhwIjoxNzkxNjQ2MjAwfQ.H0A0Z97FC0auMVF0d09jFp-Y2ZnY1pKUT3yTWc-pGLk " =1265x782") ## 2. Check for Marketplace Marketplace lets you install and update Spicy Lyrics directly from Spotify. Reopen Spotify and look for the **Marketplace** button in the top-left corner of Spotify. ![Marketplace button in Spotify's top-left corner](https://guides.spicylyrics.org/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzFhNjFjY2M5LTM4MWYtNGE5MS1iYWJjLTlhYjMyZDJiOGNjOC9iNmZlNjFkZi1mMTQ3LTQ0NTMtODRjNS1jNDgzMjcyMDNkY2MvMDItbWFya2V0cGxhY2Utc2lkZWJhci5wbmciLCJ0eXBlIjoiYXR0YWNobWVudCIsImlhdCI6MTc5MTU1OTgwMCwiZXhwIjoxNzkxNjQ2MjAwfQ.jxGED9nUJOith8QnFt5XYYvgqHgco-_2RK9D4fYbdTw " =567x343") If Marketplace is there, continue to the next step. If it is missing, install it using the command for your operating system. ### Windows Open **PowerShell** and run: ```powershell iwr -useb https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.ps1 | iex ``` ### macOS/Linux Open a terminal and run: ```bash curl -fsSL https://raw.githubusercontent.com/spicetify/marketplace/main/resources/install.sh | sh ``` When the installation finishes, fully close and reopen Spotify. :::info **Marketplace still missing?** Run `spicetify apply`, then fully close and reopen Spotify. ::: ## 3. Install Spicy Lyrics 1. Open **Marketplace** from Spotify's top-left corner. 2. Select **Extensions**. 3. Search for **Spicy Lyrics**. ![Search result for "Spicy Lyrics" in Marketplace](https://guides.spicylyrics.org/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzFhNjFjY2M5LTM4MWYtNGE5MS1iYWJjLTlhYjMyZDJiOGNjOC8wYmZmOTg1OS0zMDZhLTQwNTMtOTRiYy1lMDNkNDIxNjZhYWEvMDMtc2VhcmNoLXNwaWN5LWx5cmljcy5wbmciLCJ0eXBlIjoiYXR0YWNobWVudCIsImlhdCI6MTc5MTU1OTgwMCwiZXhwIjoxNzkxNjQ2MjAwfQ.3w-UNW3e182MBuin5tZ3q6r5sGgcIi83HKH6Qgl6uek " =1729x1029") 4. Open the Spicy Lyrics result. 5. Select **Install**.![Spicy Lyrics extension page with the "Install" button](https://guides.spicylyrics.org/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzFhNjFjY2M5LTM4MWYtNGE5MS1iYWJjLTlhYjMyZDJiOGNjOC8yODhjMGZhMS02ZTU4LTRlZGItYTljMy0zNTcxMDY4NTYxZWIvMDQtaW5zdGFsbC1zcGljeS1seXJpY3MucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTE1NTk4MDAsImV4cCI6MTc5MTY0NjIwMH0.Ll79bDKkBRuwEmq84Dp1ZH1g9iQ7CwG5UUhxBzojk8w " =1728x1027") 6. Select **Reload now** if Spotify asks you to reload. ## 4. Check that it works Play a song with lyrics and open Spicy Lyrics using its button next to Spotify's standard lyrics button. If the Spicy Lyrics interface appears, installation is complete. ![Spicy Lyrics page open while a song is playing](https://guides.spicylyrics.org/api/files.get?sig=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1cGxvYWRzLzFhNjFjY2M5LTM4MWYtNGE5MS1iYWJjLTlhYjMyZDJiOGNjOC83MTE4ZjEwYy05ZjFhLTRkMTAtYjU4OC0yNDE1ZGY0MGU3NzcvMDUtc3BpY3ktbHlyaWNzLXdvcmtpbmcucG5nIiwidHlwZSI6ImF0dGFjaG1lbnQiLCJpYXQiOjE3OTE1NTk4MDAsImV4cCI6MTc5MTY0NjIwMH0.9XaiY_FazK97mfMSDZI9mhfiGxYFBhzsracm8fKarws " =1715x1030") ## Useful things to know * **Spotify Free works.** Spicy Lyrics does not require Spotify Premium, although behavior can vary by Spotify version, platform, account, or region. * **Marketplace installations normally update automatically.** If an update does not appear or the extension stops loading, restart Spotify and check the [Spicy Lyrics status page](https://status.spicylyrics.org/) before reinstalling anything. * **Online lyric lookup needs an internet connection.** Lyrics saved through the Lyrics Manager's persistent local library remain available on that device, but this does not make the full online catalog available offline. * **Available lyrics vary by track.** A different release of the same song may have different lyrics or a different synchronization type. ## Troubleshooting ### Marketplace is not showing Run: ```bash spicetify apply ``` Then fully close and reopen Spotify. If Marketplace is still missing, reinstall it using the command in [Check for Marketplace](#2-check-for-marketplace). ### Spicy Lyrics is installed but does not appear Fully close and reopen Spotify. Then open **Marketplace**, check your installed extensions, and confirm that Spicy Lyrics is installed and enabled. If it still does not appear, run: ```bash spicetify apply ``` If Spicy Lyrics shows a connection error or never finishes loading, see [Spicy Lyrics can't connect](#spicy-lyrics-cant-connect). ### Spicy Lyrics can't connect This means Spicy Lyrics can't reach its servers. 1. Check the [status page](https://status.spicylyrics.org/) for an outage. 2. Open [api.spicylyrics.org/version](https://api.spicylyrics.org/version) in your web browser. It should show only a version number, such as `6.3.98`. 3. If that page doesn't load or is blocked, something on your connection is blocking Spicy Lyrics. Try a VPN or [Cloudflare WARP](https://one.one.one.one/) and see whether that fixes it. 4. Antivirus software sometimes blocks Spicy Lyrics' domains. If so, add `*.spicylyrics.org` and `*.spikerko.org` as exceptions in your antivirus. If the page loads but Spicy Lyrics still can't connect, check the console for errors: 1. Open the developer tools with **Ctrl + Alt + I** (**Cmd + Option + I** on macOS). If they don't open, run `spicetify enable-devtools` first. 2. Open the **Console** tab and type `spicy` in the filter bar. 3. Include those messages when you [ask for help](#still-having-problems). ### Spicetify disappeared after Spotify updated Spotify updates can remove Spicetify's modifications. Run: ```bash spicetify backup apply ``` If that does not work, update Spicetify: ```bash spicetify update ``` If the update does not fully reapply the changes, run: ```bash spicetify restore backup apply ``` **Tip: reapply Spicetify automatically (Windows).** Open Spotify with a shortcut that runs `spicetify auto` instead of Spotify's own shortcut. Each time, Spicetify checks whether Spotify has updated, reapplies itself if needed, and then opens Spotify. 1. Right-click your desktop and select **New → Shortcut**. 2. Enter `spicetify auto` as the location, then select **Next**. 3. Name it **Spotify** and select **Finish**. Use this shortcut to open Spotify from now on. You can pin it to the taskbar or Start menu. It only helps when your Spicetify version already supports the new Spotify version. If no compatible Spicetify update is available yet, either wait for support for the new Spotify version or [downgrade Spotify](#spotify-version-not-supported-by-spicetify). ### Spotify version not supported by Spicetify Spotify sometimes releases an update before Spicetify supports it. When that happens, Spicetify, Marketplace, and Spicy Lyrics can stop loading until Spicetify catches up. **Update Spicetify first.** This fixes most cases, and you won't need to downgrade: ```bash spicetify update ``` Then run `spicetify backup apply` and reopen Spotify. If it still doesn't work, check which Spotify versions the latest Spicetify supports. The notes for the [latest stable Spicetify release](https://github.com/spicetify/cli/releases/latest) list the supported range for Windows, macOS, and Linux. The same list is posted in the [#compatibility](https://discord.com/channels/842219447716151306/1298399011509899375) channel of the Spicetify Discord server. If your Spotify version is newer than the newest supported one, you can install an older Spotify version and block Spotify updates until Spicetify adds support. :::warning Only download Spotify from the source below, and read what each command does before you run it. Don't run commands or installers from random links. ::: #### Download a supported Spotify version 1. Open [LoadSpot](https://loadspot.pages.dev/versions), an unofficial archive of Spotify's desktop installers. It isn't run by Spotify or Spicy Lyrics. 2. Select your operating system. 3. Download the **newest version that Spicetify supports**. Most Windows PCs and Intel Macs use **x64**. Apple silicon Macs (M1 and newer) use **arm64**. On Windows, you can check that the installer is genuine by right-clicking it and opening **Properties → Digital Signatures**. It should be signed by Spotify. #### Windows :::info This doesn't work with the **Microsoft Store** version of Spotify, which Spicetify doesn't properly support. Uninstall it and use the installer from LoadSpot instead. ::: 1. Fully close Spotify, including from the system tray. 2. Run the installer you downloaded. You don't need to uninstall your current version first. 3. When the older version opens, fully close Spotify again. 4. Open **Command Prompt** (not PowerShell) and run these commands one at a time: :::info The `rmdir` command may fail or say that the folder can’t be found; ignore it and continue. ::: ``` rmdir /s /q "%localappdata%\Spotify\Update" mkdir "%localappdata%\Spotify\Update" icacls "%localappdata%\Spotify\Update" /deny "%username%":D icacls "%localappdata%\Spotify\Update" /deny "%username%":R ``` | Command | What it does | |---------|--------------| | `rmdir` | Deletes Spotify's update folder, including any update it already downloaded. | | `mkdir` | Creates an empty update folder. | | `icacls … :D` | Stops the folder from being deleted. | | `icacls … :R` | Stops the folder from being read, so Spotify can't install updates from it. | 5. Apply Spicetify again. This works in Command Prompt or PowerShell: ```bash spicetify backup apply ``` 6. Open Spotify and check that Spicy Lyrics loads. The `spicetify spotify-updates block` command doesn't currently work on Windows, so use the manual steps above. #### macOS 1. Quit Spotify completely (**Cmd + Q**). 2. Unpack the downloaded archive until you get a folder named `Contents`. 3. In Finder, go to **Applications**, right-click **Spotify**, and select **Show Package Contents**. 4. Delete the `Contents` folder you see there and replace it with the `Contents` folder you unpacked. 5. Open Terminal and block updates: ```bash spicetify spotify-updates block ``` If that command doesn't work, empty the `~/Library/Application Support/Spotify/PersistentCache/Update` folder in Finder, then run: ```bash chflags uchg ~/Library/Application\ Support/Spotify/PersistentCache/Update ``` 6. Apply Spicetify again: ```bash spicetify backup apply ``` 7. Open Spotify and check that Spicy Lyrics loads. #### Linux On Linux, Spotify is updated by your package manager, not by Spotify itself. Install a supported version and hold it using your package manager. Snap installations of Spotify can't be modified by Spicetify. After installing, run `spicetify backup apply`. #### If playback breaks after downgrading Spicetify's [FAQ](https://spicetify.app/docs/faq) recommends deleting Spotify's local data and reopening Spotify: * **Windows:** everything in `%localappdata%\Spotify` **except** the `Update` folder * **macOS:** everything in `~/Library/Application Support/Spotify` except `PersistentCache/Update` This clears Spotify's cache, including songs downloaded for offline listening. #### Turning Spotify updates back on Leave updates blocked until Spicetify supports a newer Spotify version. Then remove the block. **Windows** (Command Prompt): ``` icacls "%localappdata%\Spotify\Update" /remove:d "%username%" rmdir /s /q "%localappdata%\Spotify\Update" ``` The first command removes the block; without it, the folder can't be deleted. **macOS** (Terminal): ```bash spicetify spotify-updates unblock ``` If you used `chflags` instead, run `chflags nouchg ~/Library/Application\ Support/Spotify/PersistentCache/Update`. Then let Spotify update (or install the newest supported version from LoadSpot), update Spicetify with `spicetify update`, and run `spicetify backup apply`. ### Spicy Lyrics opens but lyrics do not load Try another song first. If the Spicy Lyrics interface opens, the extension itself is installed. If the problem affects one song, confirm that you opened the intended version or try another release of the same recording. Different releases can have different lyric availability. If lyrics are missing, outdated, or wrong: 1. Open Spicy Lyrics settings and clear the lyrics cache. 2. Reopen the song. 3. Check the [status page](https://status.spicylyrics.org/) for an outage. 4. Search [#lyric-issues](https://discord.com/channels/1369992682214264993/1370023661830148106) before reporting it. Include the exact Spotify song link when asking for help. If several unrelated songs fail, check the status page before reinstalling anything. ## Manual installation (advanced) :::warning Manual installation is not recommended. Use Marketplace unless you specifically need to install Spicy Lyrics manually. ::: 1. Make sure [Spicetify](https://spicetify.app/) is installed. 2. Download the latest [`spicy-lyrics.mjs`](https://github.com/Spikerko/spicy-lyrics/blob/main/builds/spicy-lyrics.mjs) file. 3. Put the file in your [Spicetify Extensions directory](https://spicetify.app/docs/customization/extensions#manual-installation). 4. Run: ```bash spicetify config extensions spicy-lyrics.mjs ``` 5. Apply Spicetify: ```bash spicetify apply ``` 6. Reopen Spotify. ## Still having problems? Check the [status page](https://status.spicylyrics.org/) first, then search [#general-support](https://discord.com/channels/1369992682214264993/1407804754159206552) and [#extension-bugs](https://discord.com/channels/1369992682214264993/1370023518313644193). If the problem has not already been reported, ask in the [Spicy Lyrics Discord server](https://discord.gg/lyrc). Include: * Your operating system * Your Spotify, Spicetify, and Spicy Lyrics versions * The exact step that failed * What you expected and what happened instead * The complete error message * The affected Spotify song link, when relevant * A screenshot, video, console error, or log that is safe to share Do not share account tokens, cookies, authorization headers, or other secrets. These details make it much easier to identify what went wrong.