In this jargon-busting guide, I'll be your digital chaperone, walking you down the aisle of coupling Sonarr – arguably everyone's top pick for personal video recorder (PVR) software – with the versatile Home Assistant. We'll start with the basics, then dive deeper into the intriguing world of custom Upcoming Media Card. On top of that, we'll take a gander at the Sonarr Upcoming Media integration just waiting to jazz up your Home Assistant Dashboard.

Disclaimer: Home Assistant Guide on piracy
The information provided in this article by Home Assistant Guide is purely for educational and informational purposes only. Home Assistant Guide does not condone, promote or endorse any form of piracy or unauthorized access to copyrighted material. We strongly advise our readers to respect the rights of content creators and abide by the relevant copyright laws. The use or misuse of the information provided in this article is solely the responsibility of the reader. Home Assistant Guide does not accept any liability for any actions taken by the reader based on the information provided in this article.
Farewell to the Upcoming Media Card: Archive in Action
As of 26th of May 2022, the repository for the Upcoming Media Card, which is used in this guide, has been sent off for archiving. Now, if you're tech-savvy enough, you can certainly still get your mitts on the files and go through the rigmarole of a manual installation. However, it's a bit like trying to resuscitate a dinosaur; the code for this relic isn't getting any fresh updates, so it's generally not the best idea.
Getting to know Sonarr
For those unacquainted, Sonarr is a genius at tracking and automatically collating data from indexers for TV shows. It's a favourite among many and, without mincing words, leaves competitors like Sick Beard and SiCKRAGE eating its dust. If the idea of automating your TV show downloads tickles your fancy, allow me to introduce Sonarr, your new digital comrade.
Like a loyal bloodhound, Sonarr keeps a sharp eye on your downloaded TV shows, giving you a heads-up for any missing episodes, and it doesn't stop there – it even goes on a hunt for new ones for you.
A word on Sonarr v3
Sonarr v3, the eagerly anticipated update, is set to unveil a treasure trove of new features. A sleek redesign, search filters, and the removal of the Drone Factory, just to name a few. Fear not, Sonarr v3 will be compatible with everything detailed in this guide. However, this guide was concocted using the most recent stable release.
Integrating Sonarr with Home Assistant
Setting up the Sonarr integration is now a walk in the park, thanks to its migration to the UI. Just click on “Configuration” in the menu, select “Integrations”, then hit the big “+” button and search for “Sonarr”.

Next, pop open Sonarr and dig into the settings. Under “General” you'll find your API key (remember, this key is as private as your diary, don't share it). Copy the key and mosey on back to Home Assistant. Paste the Sonarr API key alongside the host (IP address), path to the API (which can be left as is), and Sonarr’s port. If everything checks out, you'll get a pat on the back with a successful integration notification.

By default, only one of the six entities will be activated. To wake up the rest, click on “1 service” and then select “Activity Sensor”. Under entities, unfold the five snoozing entities. You can then click on each entity individually and bring them to life.
Sonarr sensors in Home Assistant
Let's dive into the nitty-gritty of the six sensors that come with the Sonarr integration in Home Assistant. What do they do and are they really worth your time? Let's find out.


Sonarr Commands (sensor.sonarr_commands)
First up is the “Sonarr Commands” sensor. If you're curious about the operations Sonarr is currently running, this sensor is your guy. But let's get real here, for most of us, Sonarr is a set it and forget it type of service. I mean, who really has time to keep tabs on every single command Sonarr is executing? Not me, that's for sure.
Sonarr Disk Space (sensor.sonarr_disk_space)
Next is the Sonarr Disk Space sensor. It's like a nosy neighbour telling you how big your Sonarr folders are getting. Personally, I've got the Glances integration keeping an eye on my Unraid rig's disk space, so I don't really need another tattle-tale.
Sonarr Queue (sensor.sonarr_queue)
Onto the Sonarr Queue sensor. As its name suggests, it's here to spill the tea on how many episodes you've got lined up in your queue.
Sonarr Shows (sensor.sonarr_shows)
Then we have the Sonarr Shows sensor, which keeps count of how many shows you've added to Sonarr. It even lists each show as an attribute. This could come in handy if you're a data visualization enthusiast and love adding snazzy graphs to your Home Assistant Dashboard.
Sonarr Upcoming (sensor.sonarr_upcoming)
The Sonarr Upcoming sensor. This one's like your personal TV guide, informing you about the number of episodes that are set to air soon and listing those episodes as attributes.
Sonarr Wanted (sensor.sonarr_wanted)
Last but not least, the Sonarr Wanted sensor. It's like a wish list, tracking how many episodes are marked as wanted and listing those shows as attributes.
Is that the end of the road?
Now, you might be thinking, “Is that all Sonarr brings to the table?” Because let's face it, none of these sensors are exactly game-changers. But hold on to your hats, folks, because there's more to Sonarr than meets the eye!
Display upcoming episodes in Home Assistant
Remember the days when you had to manually check when the next episode of your favourite show was airing? Yeah, those days are long gone. With a little help from a custom integration and a Home Assistant Dashboard card, your Home Assistant can now keep track of your upcoming episodes and display them on your frontend.
So, how does this magic happen, you ask? It all starts with installing two components from HACS:
In non-techy language, think of these components as the nuts and bolts that make this whole operation possible.
Once you've got these two installed, it's time to get your hands dirty and add the custom integration. Don't worry, it's not as scary as it sounds. All you need to do is type in a few lines of YAML code. It's kind of like sending your Home Assistant a text message telling it what to do. Here's what the text would look like:
---
sensor:
- api_key: YOUR_API_KEY
days: 7
host: YOUR_HOST
max: 10
platform: sonarr_upcoming_media
port: YOUR_PORT
ssl: false
Just like any text, this one also needs some personal information – your API key, your host, and your port. It's like giving your Home Assistant the keys to your car and telling it where to go.
Now, the Upcoming Media Card is where you can really let your creativity shine. This is like your Home Assistant's wardrobe – you can dress it up however you want. The variables given on the GitHub page let you customize the card to your heart's content.
Using the Sonarr Upcoming Media integration with this card lets you create Lovelace cards that are as unique as you are. So, go ahead and give it a try. Who knows, you might just find your inner designer.
