This information is for advanced users. It is recommended to use the installer script from the previous section.
sudo apt-get install -y git python3-dev python3-pillow cython3
There is good information found there in various README's and that might be all you need. The information that follows serves more as a general example of how to get the code and build the main targets.
Clone and Build
The project is makefile based, so it is fairly easy to clone the repo and build the target(s):
git clone https://github.com/hzeller/rpi-rgb-led-matrix.git cd rpi-rgb-led-matrix make
The default target builds the library as well as the C examples found in the examples-api-use subdirectory. It should be possible to run those examples after the build completes:
cd examples-api-use sudo ./demo -D 0
Dealing with "quality" vs. "convenience"
The default build uses a hardware subsystem on the Pi that is also used for audio on HDMI and the 1/8" jack. This is the "quality" option referred to by the installer script and it also requires connecting GPIO 4 to 18 on the HAT/Bonnet. So there is a hardware resource conflict that must be resolved. The demo programs will report this with the following message:
=== snd_bcm2835: found that the Pi sound module is loaded. === Don't use the built-in sound of the Pi together with this lib; it is known to be incompatible and cause trouble and hangs (you can still use external USB sound adapters). See Troubleshooting section in README how to disable the sound module. You can also run with --led-no-hardware-pulse to avoid the incompatibility, but you will have more flicker. Exiting; fix the above first or use --led-no-hardware-pulse
The other option is to disable the hardware pulsing feature of the RGB matrix driver software. This is the "convenience" option referred to by the installer script.
More info on these two options:
Option 1: Disable Sound for Hardware Pulsing ("quality")
To disable the Pi audio, blacklist it. Create a file named /etc/modprobe.d/blacklist-rgb-matrix.conf with the contents:
blacklist snd_bcm2835
and then reboot the Pi.
Option 2: Disable Hardware Pulsing ("convenience")
The command line parameter --led-no-hardware-pulse can be used to turn off this feature in the RGB matrix driver software at run time:
sudo ./demo --led-no-hardware-pulse -D 0
It can also be disabled at build time using the DISABLE_HARDWARE_PULSES preprocessor directive:
make USER_DEFINES="-DDISABLE_HARDWARE_PULSES"
Python Build
There are two targets for this: build-python and install-python. The install target uses an older (setup.py) approach. However, it seems to generally work OK to create and activate a Python virtual environment and then use the install-python target:
Make is run here without sudo since we are installing into a local user directory, i.e. the venv.
python3 -m venv test source test/bin/activate cd rpi-rgb-led-matrix make install-python
It also works to use the build-python target and then manually run setup.py with a virtual environment active. The build-python and install-python targets are dependent on the main library target, so if the goal is to have Python bindings, either of those can be used as the build target, i.e. just build everything in one make execution.
Page last edited July 15, 2025
Text editor powered by tinymce.
