Spicetify is a free, open-source command-line tool for customizing the Spotify desktop client on Windows, macOS, and Linux. It changes colors and interface styling, runs extensions, and adds custom pages inside Spotify. Users can control these changes through configuration files and commands, with an optional Marketplace interface for browsing customizations.
Apply a configuration
Spicetify keeps its choices in config-xpui.ini. The config command displays existing settings, reads one value, or writes several values together. Users select a theme folder and color scheme, then choose extension filenames or custom-app folders. Extension and app entries form lists, so adding an entry preserves the others. A removal suffix takes one entry out.
The apply command turns those choices into client changes. It copies the necessary resources and loads the selected styles, extensions, and custom apps into Spotify. Editing the configuration alone does not apply a customization.
Color schemes
A theme separates its color definitions from its CSS rules. Spicetify converts values from color.ini into CSS variables, while user.css changes fonts, spacing, layout, and other visual details. Theme folders can also carry JavaScript and assets such as images or fonts.
Many themes offer several named schemes within the same color file. Selecting another scheme changes the palette without selecting another theme. The color command can edit individual theme colors using hexadecimal or RGB values. Separate switches control custom CSS, color replacement, and theme JavaScript, allowing users to enable only the parts they want.
Home and sidebar layout
The home configuration option adds a mode for rearranging sections on Spotify’s home page. Users enter that mode through the profile menu and hover over a section to reveal its customization buttons.
Sidebar configuration works with the navigation items instead. Its configuration mode exposes controls for sticking, hiding, and rearranging those entries. These layout controls operate separately from the theme’s palette.
Extension controls
Extensions run JavaScript alongside Spotify’s main interface. They can add buttons, respond to player activity, or change existing behavior. Several extensions accompany Spicetify:
- Full App Display opens a fullscreen album-art view from a button. A double-click exits, while a right-click opens its settings.
- Keyboard Shortcut adds keyboard navigation, including sidebar switching, page scrolling, and a key-driven navigation mode.
- Loopy Loop takes start and end markers on the progress bar, then repeats that portion of the current track.
Users enable the extension filenames they want and apply the configuration. Removing an extension from that list removes its contribution when Spicetify applies the new selection.
New pages in the sidebar
Custom apps create dedicated pages in Spotify. Each app supplies JavaScript with a render function and a manifest that describes its name, icons, and related files. Enabling its folder adds an entry to Spotify’s sidebar.
Lyrics Plus displays synchronized lyrics from several providers, with provider and color choices in its settings. New Releases gathers releases from followed artists and podcasts; its filters limit results by time range and release type.
Marketplace
Spicetify Marketplace is an optional custom app for browsing themes, extensions, and small CSS snippets within Spotify. Search and category browsing lead to item details, where users can select a customization. Most items take effect without a full restart.
The Installed tab manages existing items through enable, disable, uninstall, and update controls. Marketplace can also list custom apps, although those can require manual configuration. Local customization files remain available through the CLI, alongside the visual catalogue.
Testing customizations
Watch mode monitors the components that its focus flags select. Theme focus watches the active theme’s color and CSS files when users enable those components. Extension and app focus follow their respective code. Live refresh updates Spotify as those files change. The refresh command also updates theme or selected component resources without performing the full apply operation.
Chromium DevTools provide inspection and debugging inside Spotify. Developers can use the Spicetify object to read player state, control playback, and register callbacks for track changes or playback progress. Those callbacks let an extension update its interface when the player changes.
Original client files
The backup command saves Spotify’s original client resources before customization. Restore replaces the modified resources with that backup while retaining the configuration and customization files. The auto command checks the client and backup states, backs up or applies changes when needed, then launches Spotify.
Spotify updates can replace customized files, requiring another backup and application cycle. A new Spotify client can also need compatibility changes in Spicetify itself. Existing themes and extensions may need their own adjustments when the client’s interface changes.
Rust preview
The Rust preview uses modules to manage customizations and includes a companion daemon. Its package commands list, install, enable, update, or delete modules. Module identifiers select registry packages. After package updates, the apply operation loads those changes into Spotify. The daemon watches Spotify’s resources and waits for the client to exit before reapplying changes after an update. This preview uses a different backup layout from the earlier CLI.
On Linux, the preview manages a separate user-owned Spotify client from official packages, installing and updating it without changing system packages.
