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 guide walks you through a complete software installation of luma.oled on a Raspberry Pi or compatible Linux-based single-board computer. You will create an isolated Python environment, install the library and its dependencies, and configure the system permissions required to communicate with your display hardware.
Luma OLED requires Python 3.9 or later. It has been tested on Python 3.9 through 3.14 and on Raspberry Pi models A, B2, 2, 3B, Zero, Zero W, 4B, and 5 running Raspberry Pi OS.
1

Create a Python virtual environment

Create an isolated virtual environment to avoid conflicts with other Python packages installed on your system.
python3 -m venv ~/luma-env
This creates a virtual environment in your home directory called luma-env with a dedicated Python executable at ~/luma-env/bin/python.
2

Install luma.oled

Install the latest version of luma.oled directly into the virtual environment using pip.
~/luma-env/bin/python -m pip install --upgrade luma.oled
Pip will automatically resolve and install luma.core and any other required Python dependencies.
3

Install system dependencies

If pip cannot install its dependencies automatically, you need to add the required system packages manually. On Raspberry Pi OS, run the following commands:
sudo apt-get update
sudo apt-get install python3 python3-pip python3-pil libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libopenjp2-7 libtiff5 -y
These packages provide the image processing libraries that Pillow needs to compile and run correctly.
If your distribution includes a pre-packaged version of Pillow, use it instead of installing from pip. On many Debian-based systems the correct package is python3-pil or python3-imaging:
sudo apt-get install python3-pil
If you are not using Raspberry Pi OS, consult your Linux distribution’s documentation to find the equivalent packages.
4

Configure interface permissions

Luma OLED communicates over hardware interfaces (SPI, I2C, GPIO) that require explicit user permissions. Add your user account to the relevant groups:
sudo usermod -a -G spi,gpio,i2c pi
Replace pi with the username of the account that will run your luma.oled programs. You will need to log out and back in for the group changes to take effect.

​
Verify the installation

Activate the virtual environment and confirm luma.oled is installed: 
~/luma-env/bin/python -c "import luma.oled; print(luma.oled.__version__)"
If the command prints a version number without errors, the installation is complete.

​
Next steps

  • Quickstart — connect a display and draw your first image
  • Hardware setup — enable I2C or SPI in the operating system and wire up your display

Build docs developers (and LLMs) love

Get started for freeTalk to us