Raspberry Pi LED Matrix Library – Installation for multiline m x n MAX7219 LED Matrices

In this Tutorial I will show you how to use the library for multilined MAX7219 Matrices I wrote (improved and extended version of JonA1961’s MAX7219array https://github.com/JonA1961/MAX7219array )




If you buy LED Dot Matrices, you should mind that these must be quadratic.

I wrote an article (german) about how to solder a MAX7219 Matrix.



To use this LED Dot Matrices you have to install the python spi library. If you already have done this you can skip this step.

If you haven’t it installed yet, i would recommend to follow this instructions: http://www.100randomtasks.com/simple-spi-on-raspberry-pi


Setup of the Matrices

Once you have soldered all LED Matrices you can connect them. For working correctly it is important to connect them like in the picture below. The first module is bottom left (seen from the front side), the next one above it. When one column is finished  you set the next module on the right side at the bottom, the next one above it and so on.


Front view (matrices are numbered)

Back view (Jumper cables from Matrix 1 go to the RPi)

Each Matrix has these Pins:

Right: CLK – CS – DIN – GND – VCC

Left: CLK – CS – DOUT – GND – VCC

The DOUT Pin of the previous matrix is connected with DIN of the following. The other Pins are also connected.

The Pins of the first Matrix are connected to the Raspberry Pi as follows:


Installing library

I created a GitHub repository, you can download it from there (make sure you have installed the github client):

git clone https://github.com/tutRPi/multilineMAX7219.git && cd multilineMAX7219

In this directory are two important files:

multilineMAX7219.py – This is the main file, which contains all functions

multilineMAX7219_fonts.py – This file contains the letters and symbols of the different fonts. If you want to add some fonts, you should edit this file.


It is important to change the multilineMAX7219.py file (Line 113/114) and set your individual MATRIX_WIDTH and MATRIX_HEIGHT.


Demo Code

To run a demo you can type

python multilineMAX7219_demo.py

and see the different effects.


In my opinion the graphic functions are espacially interesting on multiline displays.
I made an easy site where you can draw images and display them on your LED Matrices:

The site you can find here.

As you see the code for the Raspberry Pi Logo (on 3×3 matrices) is given. I can import it in python:

logo = [[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,1,0,0,1,1,0,0,0,0,0,0,0,1,1,1,0],[0,0,0,1,1,1,1,1,0,0,0,0,1,1,1,0,0,0,0,1,0,0,1,0],[0,0,1,1,0,0,1,0,0,0,0,0,1,0,0,1,1,1,1,0,0,0,0,1],[0,0,1,0,0,0,0,1,1,1,1,1,1,1,0,0,1,1,0,0,0,1,0,1],[0,1,0,0,0,0,1,1,1,1,0,0,1,1,1,0,0,1,0,0,0,1,0,1],[0,1,1,1,1,1,1,1,1,0,0,0,0,1,1,0,0,1,0,0,1,0,0,1],[0,1,1,1,1,1,1,1,1,0,0,0,0,1,1,1,1,1,0,0,1,0,1,0],[1,1,0,1,1,0,0,1,1,0,0,0,0,1,0,0,1,1,0,1,0,0,1,0],[1,0,0,1,0,0,0,1,1,1,0,0,1,1,0,0,1,1,1,0,0,0,1,0],[1,0,0,1,0,0,0,0,1,1,1,1,1,1,0,0,0,1,1,1,1,1,0,0],[1,0,0,1,0,0,0,0,1,1,1,1,1,1,0,0,0,1,1,1,1,1,0,0],[1,0,0,1,0,0,0,1,1,1,0,0,1,1,0,0,1,1,1,0,0,0,1,0],[1,1,0,1,1,0,0,1,1,0,0,0,0,1,0,0,1,1,0,1,0,0,1,0],[0,1,1,1,1,1,1,1,1,0,0,0,0,1,1,1,1,1,0,0,1,0,1,0],[0,1,1,1,1,1,1,1,1,0,0,0,0,1,1,0,0,1,0,0,1,0,0,1],[0,1,0,0,0,0,1,1,1,1,0,0,1,1,1,0,0,1,0,0,0,1,0,1],[0,0,1,0,0,0,0,1,1,1,1,1,1,1,0,0,1,1,0,0,0,1,0,1],[0,0,1,1,0,0,1,0,0,0,0,0,1,0,0,1,1,1,1,0,0,0,0,1],[0,0,0,1,1,1,1,1,0,0,0,0,1,1,1,0,0,0,0,1,0,0,1,0],[0,0,0,0,0,0,0,0,1,0,0,1,1,0,0,0,0,0,0,0,1,1,1,0],[0,0,0,0,0,0,0,0,0,1,1,1,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]]

And now you can draw it with


For more details look into the multilineMAX7219_demo.py file and multilineMAX7219.py where all functions are described.


I made an example video (this is a short version of the demo file):

34 Responses

  1. Hi,
    I have bought a 4 x 8×8 Matrix Display and have installed your library.
    It’s working in general but everything is rotated by 90 degreees.
    Is there a way to rotate everthing?

    Schönen Gruß

    • did you find a sollution? I have the same problem and can’t find the correct library change to do. also, I have 4 led 8×8 matrix on the same PCB, so I cannot rotate each individually.


      • I have not found a solution to rotate them.
        But I only needed the numbers (for a digital clock), so I created my own set of numbers:

        During setup

        intNull = [[0,0,1,1,1,1,0,0],[0,1,1,0,0,1,1,0],[0,1,1,0,0,1,1,0],[0,1,1,0,0,1,1,0],[0,1,1,0,0,1,1,0],[0,1,1,0,0,1,1,0],[0,0,1,1,1,1,0,0],[0,0,0,0,0,0,0,0]]
        intEins = [[0,0,1,1,0,0,0,0],[0,1,1,1,0,0,0,0],[0,0,1,1,0,0,0,0],[0,0,1,1,0,0,0,0],[0,0,1,1,0,0,0,0],[0,0,1,1,0,0,0,0],[1,1,1,1,1,1,0,0],[0,0,0,0,0,0,0,0]]
        intZwei = [[0,1,1,1,1,0,0,0],[1,1,0,0,1,1,0,0],[0,0,0,0,1,1,0,0],[0,0,1,1,1,0,0,0],[0,1,1,0,0,0,0,0],[1,1,0,0,1,1,0,0],[1,1,1,1,1,1,0,0],[0,0,0,0,0,0,0,0]]
        intDrei = [[0,1,1,1,1,0,0,0],[1,1,0,0,1,1,0,0],[0,0,0,0,1,1,0,0],[0,0,1,1,1,0,0,0],[0,0,0,0,1,1,0,0],[1,1,0,0,1,1,0,0],[0,1,1,1,1,0,0,0],[0,0,0,0,0,0,0,0]]
        intVier = [[0,0,0,1,1,1,0,0],[0,0,1,1,1,1,0,0],[0,1,1,0,1,1,0,0],[1,1,0,0,1,1,0,0],[1,1,1,1,1,1,1,0],[0,0,0,0,1,1,0,0],[0,0,0,1,1,1,1,0],[0,0,0,0,0,0,0,0]]
        intFunf = [[1,1,1,1,1,1,0,0],[1,1,0,0,0,0,0,0],[1,1,1,1,1,0,0,0],[0,0,0,0,1,1,0,0],[0,0,0,0,1,1,0,0],[1,1,0,0,1,1,0,0],[0,1,1,1,1,0,0,0],[0,0,0,0,0,0,0,0]]
        intSech = [[0,0,1,1,1,0,0,0],[0,1,1,0,0,0,0,0],[1,1,0,0,0,0,0,0],[1,1,1,1,1,0,0,0],[1,1,0,0,1,1,0,0],[1,1,0,0,1,1,0,0],[0,1,1,1,1,0,0,0],[0,0,0,0,0,0,0,0]]
        intSieb = [[1,1,1,1,1,1,0,0],[1,1,0,0,1,1,0,0],[0,0,0,0,1,1,0,0],[0,0,0,1,1,0,0,0],[0,0,1,1,0,0,0,0],[0,0,1,1,0,0,0,0],[0,0,1,1,0,0,0,0],[0,0,0,0,0,0,0,0]]
        intAcht = [[0,1,1,1,1,0,0,0],[1,1,0,0,1,1,0,0],[1,1,0,0,1,1,0,0],[0,1,1,1,1,0,0,0],[1,1,0,0,1,1,0,0],[1,1,0,0,1,1,0,0],[0,1,1,1,1,0,0,0],[0,0,0,0,0,0,0,0]]
        intNeun = [[0,1,1,1,1,0,0,0],[1,1,0,0,1,1,0,0],[1,1,0,0,1,1,0,0],[0,1,1,1,1,1,0,0],[0,0,0,0,1,1,0,0],[0,0,0,1,1,0,0,0],[0,1,1,1,0,0,0,0],[0,0,0,0,0,0,0,0]]

        and in the program:

        if (x == “0”):
        LEDMatrix.gfx_sprite_array(intNull, 0,0)
        if (x == “1”):
        LEDMatrix.gfx_sprite_array(intEins, 0,0)
        if (x == “2”):
        LEDMatrix.gfx_sprite_array(intZwei, 0,0)

        Hope this helps for you.

  2. Hello,
    I have a problem with this, when i try the demo i have an error :
    Python 3.5.3 (/usr/bin/python3)
    >>> %Run multilineMAX7219_demo.py
    File “/home/pi/multilineMAX7219/multilineMAX7219.py”, line 433
    for g_y in range(MATRIX_HEIGHT*8):
    SyntaxError: inconsistent use of tabs and spaces in indentation
    Can you help me with these ?

  3. Hi,
    So I bought the LED matrix, and everything’s great, but I’m wondering how to change the colors on the LED matrix? Any ideas?

  4. Hi,
    i followed the guide but when i run the demo file there is no error, but there is also nothing appearing on the matrix.

    I am using a newly flashed Pi 3B+

    Thanks for any help

  5. File “/home/pi/Projects/multilineMAX7219/multilineMAX7219.py”, line 433
    for g_y in range(MATRIX_HEIGHT*8):
    TabError: inconsistent use of tabs and spaces in indentation

    Can you help me with this error ?

    • happened to me as well , just go to the line the error is in (433) and delete some of the indentations

  6. happened to me as well , just go to the line the error is in (433) and delete some of the indentations

  7. Hi,

    If you want to try something different, I’d like to show you my GPL’d project (https://gitlab.com/robarago/max7219mod). It’s a native kernel driver for the max7219 chip plus a direct C library, a command line program and a microservice HTTP service for remote operation. It has some unique features like non-blocking queued operations, support for GNU/Linux console fonts and it’s fast!

    Please, send me a message if you have any issue or want some more information.


  8. I’m trying to do a 32×32 display (4x 8×32 MAX7219 modules) and having no luck with arduino/esp32. I considered using a Pi (any model) in the beginning because I know there are limitations using arduino. This is the closest I’ve found to using the 8×32 modules stacked on top of each other and would definitely love to finish my project.

    My project is having a 32×32 led matrix display that I can shoot over a image/text (still or animated) wirelessly. I know there are 32×32 boards dedicated for this sort of thing, but I’m trying to use parts that I have on hand.


Leave a Comment

Your email address will not be published.

Subscribe to Raspberry Pi Tutorials and don't miss any new Tutorial!