If you manually installed things, this was likely already taken care of.
The installer script builds the Python bindings, but does not install them. We want to install things into a Python virtual environment. So the first step is to create the venv and activate it. We'll call the venv rgbmatrix and locate it in the pi user's home folder:
cd python3 -m venv rgbmatrix source rgbmatrix/bin/activate
Next, cd back into the directory the repo was cloned into and run make with the install-python target:
cd rpi-rgb-led-matrix/ make install-python
That should install the Python support into the venv.
There are some Python examples found in the bindings/python/samples subfolder that can be used to test the setup. The examples must be run with sudo, which can be tricky when used within a venv. The Python virtual environment guide has more information on how to deal with this.
Here is an example:
cd bindings/python/samples/ sudo -E env PATH=$PATH python3 simple-square.py --led-rows=32 --led-cols=32 --led-gpio-mapping=adafruit-hat
That should result in output on the RGB matrix that looks like this:
Parameters can be set via the command line. Change the following parameters as needed for your setup:
-
--led-row=set this to the number of LEDs in each matrix row (default=32) -
--led-cols=set this to the number of LEDs in each matrix column (default=32) -
--led-gpio-mapping=set this toadafruit-hatoradafruit-hat-pwm(default=regular)
Another Basic Example
The examples in the library repo have a sort of object-orientated design which may make things look overly complicated. Additionally, there is a lot of code dealing with parsing the command line options. All of the command line parameters can be configured directly in code.
Here is another example to show more simply how the RGB matrix can be used in Python:
import time
from random import randrange
from rgbmatrix import RGBMatrix, RGBMatrixOptions
options = RGBMatrixOptions()
options.hardware_mapping = 'adafruit-hat'
options.rows = 32
options.cols = 32
matrix = RGBMatrix(options = options)
while True:
matrix.Clear()
for _ in range(1000):
r = randrange(256)
g = randrange(256)
b = randrange(256)
x = randrange(32)
y = randrange(32)
matrix.SetPixel(x, y, r, g, b)
time.sleep(0.01)
The general idea is to create an instance of the RGBMatrixOptions class and then set things as desired. Then create an instance of the RGBMatrix class and pass in the options.
The only documentation other than the examples is the source code itself, as linked from the repo readme. Here is a terse summary of the available functions and properties.
The RGBMatrixOptions class has the following properties:
brightness chain_length cols daemon disable_hardware_pulsing drop_priv_group drop_priv_user drop_privileges gpio_slowdown hardware_mapping inverse_colors led_rgb_sequence limit_refresh_rate_hz multiplexing panel_type parallel pixel_mapper_config pwm_bits pwm_dither_bits pwm_lsb_nanoseconds row_address_type rows scan_mode show_refresh_rate
The RGBMatrix class has the following functions and properties:
Clear() CreateFrameCanvas() Fill() SetImage() SetPixel() SetPixelsPillow() SwapOnVSync() brightness height luminanceCorrect pwmBits width
Page last edited January 14, 2026
Text editor powered by tinymce.
