The easiest way to install the integration is via the Home Assistant Community Store (or HACS for short). Check out the [HACS Install Documentation](https://hacs.xyz/docs/use/) for more information on how to install HACS in your Home Assistant environment.
If you do not want to use HACS, you can also install the integration manually by copying files from the GitHub project.
Both installation types are covered below.
## Requirements
The following requirements must be met prior to installing the SpotifyPlus Integration.
* A Spotify Premium account is required; Free accounts will no longer work as of 2026/02/11 [due to Spotify Developer Access changes](https://developer.spotify.com/blog/2026-02-06-update-on-developer-access-and-platform-security).
* Home Assistant 2024.10+ release.
## HACS Installation Instructions
It's recommended that you utilize the local HA instance URL (e.g. `http://homeassistant.local:8123`) when installing via HACS, as some public URL access providers (Cloudfare, etc) block access to the GitHub repository site by default unless properly configured. It is also recommended that you use a desktop browser (not a mobile / tablet device) for the install process.
Use the following link to open (and add) the custom repository in HACS:
[](https://my.home-assistant.io/redirect/hacs_repository/?owner=thlucas1&repository=homeassistantcomponent_spotifyplus&category=Integration)
You can then jump to the [Download Repository](#download-repository) steps that will walk you thru the repository download process.
If the above does not work for you, then use the following steps to add the custom repository manually.
- Starting at your Home Assistant main dashboard, click on the `HACS` main menu item to display the current list of HACS Repositories. I would suggest filtering the list of entries by entering `SpotifyPlus` in the `Search` textbox field. Note that in the screen capture below, I have the [SpotifyPlus Card](https://github.com/thlucas1/spotifyplus_card/wiki/Card-Features#player-section) repository installed, but not the SpotfyPlus Integration repository.
- Click on the 3-dot overflow menu in the upper right, and select `custom repositories` item.
This will open the HACS Custom Repositories dialog.
- Copy / paste the following url in the `Repository` textbox, and select `Integration` for the `Type` entry.
```
https://github.com/thlucas1/homeassistantcomponent_spotifyplus
```
> [!IMPORTANT]
> Make sure you select `Integration` for the `Type` entry! Anything else will cause cause the installation to fail!
- Click on `Add` to add the custom repository to the HACS Repository List.
Give this 10 to 30 seconds to complete, as there is not visual "processing" indicator to let you know something is happening. You should see the list behind the dialog update once it completes.
- Close the Custom Repositories dialog.
This will display the `SpotifyPlus` repository entry under the "New" group of HACS Repository List entries.
It will look like this:
- Click on the `SpotifyPlus` repository entry to display the repository details.
### Download Repository
Note at this point you have only added the repository to the HACS Repository List. Now it's time to actually download the contents of the repository itself. You should now be displaying the repository details, which will also display a `Download` button (lower right corner) that can be used to download the repository contents.
- Click on the `Download` button to start the repository download process.
This will display the download Confirmation dialog, which displays the repository version that will be downloaded as well as where it will be stored on the file system. You should download the latest repository version by default (unless you are asked by the developer to download a specific repository version for testing purposes).
- Click on the Confirmation dialog `Download` button to start the process, which will download the repository contents to the location specified in the Confirmation dialog (e.g. `config/custom_components/spotifyplus`).
- After the download completes, you can close the HACS Custom Repositories dialog.
This will display the `SpotifyPlus` repository entry under the "Pensing Restart" group of HACS Repository List entries.
It will look like this:
- Restart Home Assistant to apply the changes.
I would also suggest clearing your browser cache prior to restart.
- Review the following topics below if using Google Chromecast or Sonos devices:
- [Extra Steps for Google Chromecast Users](#extra-steps-for-google-chromecast-users)
- [Extra Steps for Sonos Users](#extra-steps-for-sonos-users)
- Proceed to the [Pre-Installation Requirements](./Device-Configuration-Options#pre-installation-requirements) wiki page for steps on how to install the integration.
## Manual Installation
- Using the tool of choice open the directory (folder) for your HA configuration (where you find `configuration.yaml`).
- If you do not have a `custom_components` directory (folder) there, you need to create it.
- In the `custom_components` directory (folder) create a new folder called `spotifyplus`.
- Download _all_ of the files from the `custom_components/spotifyplus/` directory (folder) in this repository.
- Place the files you downloaded in the new directory (folder) you created.
- Restart Home Assistant; I would also suggest clearing your browser cache prior to restart.
- Review the following topics below if using Google Chromecast or Sonos devices:
- [Extra Steps for Google Chromecast Users](#extra-steps-for-google-chromecast-users)
- [Extra Steps for Sonos Users](#extra-steps-for-sonos-users)
- Proceed to the [Pre-Installation Requirements](./Device-Configuration-Options#pre-installation-requirements) wiki page for steps on how to install the integration.
## Configuration
Most configuration of the integration is done in the UI, but not ALL of it; check out the [Device Configuration Options](./Device-Configuration-Options) wiki page for more details.
## Extra Steps for Sonos Users
There are a couple of extra SpotifyPlus configuration steps for Sonos environments. Sonos devices are considered "restricted" by Spotify Connect, so they require a more powerful authorization token to transfer playback to the device.
Ensure you have installed the Spotify Service via the Sonos App. This will enable Spotify Connect for your Sonos account.
Check out the following wiki docs for more information:
- [Spotify Desktop Player Authentication Configuration](./Device-Configuration-Options#spotify-desktop-player-authentication-configuration)
#### Limitations
For Sonos devices, all content is played on the device using the local queue when the play context / tracks services are called. The local queue content that is currently playing will be different than what the Spotify Web API is currently reporting as playing. Unfortunately, Spotify developers disabled the ability to play context / tracks under Spotify control for Sonos devices! Note that the official Spotify Apps (Desktop / Web / Mobile) utilize the Spotify Embedded Client to control the device, which does not have these limitations like the Spotify Web API does.
## Extra Steps for Google Chromecast Users
There is an extra SpotifyPlus configuration step for Google Chromecast environments, which enables HA to transfer playback to idle Chromecast devices as well as support multiple Spotify user accounts.
Check out the following wiki docs for more information:
- [Google Chromecast Device Support](./Device-Configuration-Options#google-chromecast-device-support)