Integrating Sonarr with Home Assistant

Disclosure: This post contains affiliate links. If you click through and make a purchase, I will earn a commission, at no additional cost to you. Read my full disclosure here.

Integrating Sonarr with Home Assistant streamlines the management of TV show downloads, offering a methodical approach for both newcomers and experienced users. This detailed guide is designed to walk you through the entire process, starting from the basics of setting up to embracing advanced features such as the Upcoming Media Card, enriching your Home Assistant Dashboard.


The guidance provided by Home Assistant Guide focuses on educational purposes, advocating for the respect of copyright laws and the rights of content creators. It's crucial to stress that the guide does not support any form of piracy or unauthorized content distribution, with the onus of responsible use lying on the user.

Sonarr: Your Digital Librarian for TV Shows

Sonarr simplifies the task of tracking, downloading, and organizing TV shows. It interacts seamlessly with both torrent clients and Usenet services, ensuring that your downloads meet your quality preferences and managing any download failures by seeking alternative sources.

The Synergy between Sonarr and Home Assistant

The essence of Sonarr's functionality mirrors the automation and simplification that Home Assistant brings to home management. Sonarr automates the tracking and downloading of TV series, akin to how Home Assistant streamlines various home automation tasks.

What’s New in Sonarr v3?

Sonarr v3 introduced an array of enhancements including a more intuitive user interface, bulk deletion of TV shows, and improved stability with the TVDB API, making the media management experience even smoother while maintaining full compatibility with Home Assistant.

Step-by-Step Integration Process

  1. Retrieve Sonarr's API Key: Begin by locating the API key in Sonarr's settings.
  2. Configure Home Assistant: Proceed to integrate Sonarr within Home Assistant by navigating to “Configuration”, then “Integrations”, and adding Sonarr with the necessary details such as API key, host IP, and port number.
  3. Enable Sonarr Entities: Post-integration, activate the various Sonarr entities to fully leverage its capabilities within Home Assistant.
Screenshot of Sonarr's General settings tab, focused on the 'Security' section. It shows toggled-off advanced settings, a 'Save' button, and fields for 'Basic (Browser pop-up)' authentication with obscured username and password. Below, an API Key is displayed with icons to copy, export, or regenerate the key, and a warning symbol indicating caution when regenerating the key.
A screenshot of a search prompt in the Home Assistant integrations. A input field has the word
A Screenshot Of The Home Assistant Dashboard Showing How The Int
Screenshot of the Home Assistant Dashboard displaying a success message for a completed configuration. It indicates 'Success! Created configuration for We found the following devices:' followed by an entry for an 'Activity Sensor (Sonarr)' with an 'Area' dropdown menu below it. A 'FINISH' button is visible at the bottom.
Sonarr Home Assistant 10

Understanding Sonarr's Capabilities in Home Assistant

By integrating Sonarr, Home Assistant users gain access to a suite of sensors each designed to optimize media management:

Screenshot showing a portion of the Home Assistant dashboard titled 'Entities'. It lists 'Sonarr Upcoming' with a count of '9 Episodes'. Below this, there is a note of '+5 disabled entities', indicating there are additional entities not currently active or visible.
Screenshot displaying the 'Entities' section of the Home Assistant dashboard. It shows an enabled 'Sonarr Upcoming' entity with '9 Episodes' and a list of other Sonarr sensor entities: 'sensor.sonarr_commands', 'sensor.sonarr_disk_space', 'sensor.sonarr_queue', 'sensor.sonarr_shows', and 'sensor.sonarr_wanted'. Each entity has a toggle switch indicating its enabled status. A button at the bottom reads 'Hide disabled', suggesting additional entities may be hidden from view.
Sonarr Home Assistant 06
Screenshot of the Home Assistant dashboard displaying various Sonarr entity statuses. It includes 'Sonarr Commands' with 1 Command, 'Sonarr Disk Space' showing 451.49 GB, 'Sonarr Queue' with 0 Episodes, 'Sonarr Shows' counting 229 Series, 'Sonarr Upcoming' listing 9 Episodes, and 'Sonarr Wanted' indicating 6364 Episodes. Each entity is accompanied by an icon representing its function: a wrench for Commands, a hard drive for Disk Space, a downward arrow for Queue, a TV screen for Shows, a calendar for Upcoming, and a clipboard for Wanted.

Showcasing Upcoming Episodes on Your Home Assistant Dashboard

By combining Home Assistant, Sonarr, and two custom components, you can display upcoming episodes directly on your Dashboard. The required two components can be installed using the Home Assistant Community Store (HACS):

Following the installation, the next step involves configuring the Sonarr Upcoming Media integration through YAML. This configuration is akin to instructing Home Assistant on what information you seek and how it should be retrieved. Here’s a basic template for the YAML configuration:

  - platform: sonarr_upcoming_media
    api_key: YOUR_API_KEY
    host: YOUR_HOST
    port: YOUR_PORT
    ssl: false
    days: 7
    max: 10

Replace the placeholders (YOUR_API_KEY, YOUR_HOST, and YOUR_PORT) with your details to grant Home Assistant access to Sonarr's upcoming episode data.

The real magic happens with the Upcoming Media Card. This is where you have the freedom to express your creativity, customizing the look and feel of how the upcoming episodes are presented on your dashboard. The variables detailed on GitHub provide you with the tools to personalize the card, making it a perfect fit for your setup.

By integrating the Sonarr Upcoming Media with the Upcoming Media Card, you create a unique and informative feature on your Dashboard. This not only enhances the aesthetic appeal of your setup but also keeps you informed about your anticipated TV shows. Dive into this integration and discover the potential to elevate your Home Assistant Dashboard's utility and appearance.

Screenshot of the 'Recently Downloaded' section in the Upcoming Media Card on the Home Assistant dashboard. It shows three TV shows: 'Louis Theroux Life on the Edge: Family…', with a timestamp of Sunday, 10:00 PM and an image of Louis Theroux standing in front of soldiers; 'The Simpsons Undercover Burns', scheduled for Monday, 02:00 AM with an illustration of the Simpsons family; and '90 Day Fiancé: Happily Ever… Tell All Part 1', also set for Monday, 02:00 AM, featuring an image from the show with the TLC logo.
A portrait photo oif Liam Alexander Colman, the author, creator, and owner of Home Assistant Guide wearing a suit.

About Liam Alexander Colman

is an experienced Home Assistant user who has been utilizing the platform for a variety of projects over an extended period. His journey began with a Raspberry Pi, which quickly grew to three Raspberry Pis and eventually a full-fledged server. Liam's current operating system of choice is Unraid, with Home Assistant comfortably running in a Docker container.
With a deep understanding of the intricacies of Home Assistant, Liam has an impressive setup, consisting of various Zigbee devices, and seamless integrations with existing products such as his Android TV box. For those interested in learning more about Liam's experience with Home Assistant, he shares his insights on how he first started using the platform and his subsequent journey.

Leave a comment

Share to...