Install Hyperion On Raspberry Pi (Step-by-step Guide)


I have Philips Hue smart lights at home and am amazed by the number of projects you can do with them. I already wrote on how to control these lights in Python, Home Assistant, etc. Hyperion is another tool you can use, with the primary goal of enhancing your TV experience by linking light colors to the movie you are watching. Let’s learn how to install it on a Raspberry Pi.

Hyperion has packages and repositories available for most operating systems and architectures, and it’s fully supported on Raspberry Pi. After adding the official repository to Raspberry Pi OS, you can install it with APT.

If you are used to installing new apps and services on your Raspberry Pi, it should be pretty straightforward, so let’s get to the point.

If you are looking to quickly progress on Raspberry Pi, you can check out my e-book here. It’s a 30-day challenge, where you learn one new thing every day until you become a Raspberry Pi expert. The first third of the book teaches you the basics, but the following chapters include projects you can try on your own.

I answer your questions - Raspberry...
I answer your questions - Raspberry Pi FAQ

Install Hyperion on Raspberry Pi

Download the Pi Glossary!
If you are lost in all these new words and abbreviations, request my free Raspberry Pi glossary here (PDF format)!

Get a supported distribution on your Raspberry Pi

Raspberry Pi Bootcamp
Sale: 10% off today.
Take it to the next level.
I'm here to help you get started on Raspberry Pi.
Learn all the skills you need in the correct order.

Hyperion is supported on many distributions (Debian, Ubuntu, Fedora, etc.), and is a lightweight application, so you can probably keep your current installation. But, make sure to have your system ready before going further:

I’m testing this for you with a Raspberry Pi 4, running Raspberry Pi OS Bullseye (64-bit). You might notice some slight changes depending on your setup, but overall the installation process would be the same.

Note: If you want to try it, Hyperion also has a custom distribution, named HyperBian. It’s a custom Raspberry Pi OS release with Hyperion pre-installed. It looks up-to-date, so it might be something to consider.

Install Hyperion

Here are the steps to install Hyperion on a Debian-based system:

  • Open a terminal or connect via SSH.
  • The first thing to do is to add the key for the Hyperion repository:
    wget -qO- https://apt.hyperion-project.org/hyperion.pub.key | sudo gpg --dearmor -o /usr/share/keyrings/hyperion.pub.gpg
  • Then, you can add the repository to your sources list:
    echo "deb [signed-by=/usr/share/keyrings/hyperion.pub.gpg] https://apt.hyperion-project.org/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hyperion.list
  • Update the package list:
    sudo apt update
  • Install Hyperion:
    sudo apt install hyperion

If everything is going well, it will install all the required packages (including Hyperion) and give you some information once complete:

Take note of the URL shown there, as you’ll need it for the next step. In theory, it should be your Raspberry Pi IP address, accessed via the 8090 port (or 8091 if you already have a service running on the default port).

You may also need to reboot your Raspberry Pi to complete the installation. Hyperion will enable SPI for you, just in case you need it with some of your lights later.
You can restart it with one command line:
sudo reboot

Master your Raspberry Pi in 30 days
Sale: 10% off today.
Download the eBook.
Uncover the secrets of the Raspberry Pi in a 30 days challenge.
Learn useful Linux skills and practice multiples projects.

Are you a bit lost in the Linux command line? Check this article first, for the most important commands to remember, and a free downloadable cheat sheet so you can have the commands at your fingertips.

Make sure it’s working properly

After the installation of Hyperion on your Raspberry Pi, you should be able to access the web interface at:
http://<IP_ADDRESS>:8090
You’ll now configure everything from here, so just make sure it’s working.

You’re almost done. You can now browse the menu and configuration options, and then tweak anything you want. For example, you can switch to your native language by clicking on the wrench icon in the top-right corner.

Reminder: Remember that all my Patreon supporters get access to this website without ads, early access to my videos and much more. You can become part of this community for as little as $3 per month & get all the benefits immediately.

Add your smart lights to Hyperion

Get My Cheat Sheet!
Grab your free PDF file with all the commands you need to know on Raspberry Pi!

Hyperion supports a large array of smart lights, so you should be able to connect to yours easily.

To add your LED to the interface, go to LED Instances > LED Output via the left menu, and select the type of controller you have.
Personally, I’m using Philips Hue smart lights, so I’ll share my experience with them. But the procedure with other brands should be similar. Obviously, if your lights are connected to the GPIO pins, there are a few additional steps, and each setup will be different.

I first tested filling the form manually, but it didn’t work. I had an “Invalid port” error in the logs (by the way, you can check the logs under System in the left menu, it will be very useful to understand any issue you might have).

Master Python on Raspberry Pi
Sale: 10% off today.
Get the eBook.
Do more with your Raspberry Pi, learn the useful concepts and take the shortcuts.
You miss half of the fun of using a Raspberry Pi if you don’t know anything about Python.

Then, I noticed that there was a wizard to connect Hyperion to my Philips Hue bridge.
This was way easier, it detected my controller automatically, I just had to press the button to allow the connection.
Once connected, my Light were available in the interface, and I just had to set their position to match my screen display colors.

The ideal setup is to have how light strip on each side of your monitor or TV.
You then have several choices to capture the media stream, depending on the hardware you use. Each setup is different, but basically, you need to configure it under “Capturing hardware” in the left main. It can be simple screen capture, or external devices, like a video capture device or even a camera.

You’ll find all the information to configure it your way on their official documentation. They also have a pretty active forum, so feel free to ask there if you are lost somewhere.

You can also watch the end of this video for a concrete example:

Raspberry Pi Resources

Not sure where to start?
Understand everything about the Raspberry Pi, stop searching for help all the time, and finally enjoy completing your projects.
Watch the Raspberry Pi Bootcamp course now.

Master your Raspberry Pi in 30 days
Don’t want the basic stuff only? If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.
Download the e-book.

VIP Community
If you just want to hang out with me and show your support, you can also join the Patreon community. I share behind-the-scenes content there and give you early access to my content. You’ll also get a shoutout when you join.
More details here.

Need help building something with Python?
Create, understand and improve any Python script for your Raspberry Pi.
Learn the essentials, step-by-step, without losing time understanding useless concepts.
Get the e-book now.

You can also find all my recommendations for tools and hardware on this page.


This tutorial doesn't work anymore? Report the issue here, so that I can update it!

0 0 votes
Article Rating

Patrick Fromaget

I'm the lead author and owner of RaspberryTips.com. My goal is to help you with your Raspberry Pi problems using detailed guides and tutorials. In real life, I'm a Linux system administrator with a web developer experience.

Subscribe
Notify of
guest
0 Comments
Inline Feedbacks
View all comments

Recent Posts

Master your Raspberry Pi - 10% off