Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rm-hull/luma.oled/llms.txt

Use this file to discover all available pages before exploring further.

This page covers the most common issues encountered when setting up and running luma.oled displays. Each section describes a symptom, explains the likely cause, and provides steps to resolve it.
Always verify that VCC and GND are connected to the correct pins before debugging software issues. Reversed polarity can permanently damage your display.
Using the ssd1306 driver on a display that has an SH1106 controller results in a small section of the expected output appearing correctly, while the rest of the display shows semi-random pixels (uninitialized memory). This is caused by differences in the required initialization sequences and how memory is mapped in the two controllers.To fix this, use the sh1106 device class instead:
from luma.core.interface.serial import i2c
from luma.oled.device import sh1106

serial = i2c(port=1, address=0x3C)
device = sh1106(serial)
A blank display is most commonly caused by one of the following:
  • Wrong I2C address — the default address is 0x3C, but some displays use 0x3D. Run i2cdetect -y 1 to confirm the address your display is responding on.
  • I2C not enabled — on Raspberry Pi, I2C must be enabled via raspi-config under Interface Options.
  • Wiring issue — double-check that SDA, SCL, VCC, and GND are all connected securely to the correct GPIO pins.
i2cdetect -y 1
Pass the detected address explicitly when creating the device:
from luma.core.interface.serial import i2c
from luma.oled.device import ssd1306

serial = i2c(port=1, address=0x3D)
device = ssd1306(serial)
When a Python script exits, the display is cleared. If your script draws to the display and then returns immediately, the output disappears before you can see it. Add a sleep() call to keep the program running long enough to observe the output:
import time
from luma.core.interface.serial import i2c
from luma.oled.device import ssd1306
from luma.core.render import canvas

serial = i2c(port=1, address=0x3C)
device = ssd1306(serial)

with canvas(device) as draw:
    draw.text((10, 10), "Hello world", fill="white")

time.sleep(10)
If i2cdetect shows no devices, work through the following checks:
  1. Confirm I2C is enabled in raspi-config under Interface Options → I2C.
  2. Reboot after enabling I2C for the change to take effect.
  3. Check dmesg for I2C-related errors:
dmesg | grep i2c
  1. Verify your wiring — SDA to GPIO 2 (pin 3), SCL to GPIO 3 (pin 5) on a Raspberry Pi.
  2. Try a lower I2C bus speed if the display is on long wires.
If you receive a permission error when opening /dev/spidev*, your user account is not in the spi group. Add your user and log out and back in for the change to apply:
sudo usermod -a -G spi $USER
Also confirm that SPI is enabled in raspi-config under Interface Options → SPI.
If Python raises ImportError: No module named luma, the library is not installed in the active Python environment. Install it with pip:
pip install luma.oled
If you are using a virtual environment, make sure it is activated before installing or running your script:
source venv/bin/activate
pip install luma.oled
Avoid installing with sudo pip when running scripts as a regular user, as this can cause environment mismatches.
Use luma.emulator to develop and test your display code without physical hardware. It renders output in a pygame window or saves frames to disk, which makes it easy to iterate quickly.
pip install luma.emulator

Build docs developers (and LLMs) love

Get started for freeTalk to us