How to Set Up an SSD1306 OLED Display with Your Raspberry Pi (Beginner-Friendly Guide)

Want to give your Raspberry Pi a slick little display? Whether you’re building a DIY dashboard, weather monitor, or mini terminal, the SSD1306 OLED display is a fun and easy way to add visuals to your Pi projects. In this guide, I’ll walk you through how to wire it up, install the necessary software, and display your first message.

? This tutorial works with Raspberry Pi 4, 3B+, Pi Zero W, and Raspberry Pi 5!

?? What You’ll Need

• Raspberry Pi (any model)
• SSD1306 OLED display (128x64 I2C version)
• Jumper wires
• Optional: Breadboard
• Internet access

?? Step 1: Wiring the SSD1306 to Your Pi

?? Step 2: Enable I2C on Raspberry Pi

Run this command in the terminal:

sudo raspi-config

Enable I2C under Interface Options, then reboot:

sudo reboot

Install I2C tools:

sudo apt-get install -y i2c-tools

Then detect the OLED:

i2cdetect -y 1

You should see an address like 0x3C.

?? Step 3: Install Required Python Libraries

pip3 install adafruit-circuitpython-ssd1306
pip3 install adafruit-blinka
pip3 install pillow

?? Step 4: Create Your First Display Script

Save this as oled_test.py:

import board
import busio
from PIL import Image, ImageDraw, ImageFont
import adafruit_ssd1306

i2c = busio.I2C(board.SCL, board.SDA)
display = adafruit_ssd1306.SSD1306_I2C(128, 64, i2c)

display.fill(0)
display.show()

image = Image.new("1", (display.width, display.height))
draw = ImageDraw.Draw(image)
font = ImageFont.load_default()

draw.text((0, 0), "Hello, Pi!", font=font, fill=255)

display.image(image)
display.show()

Run it:

python3 oled_test.py

??? Troubleshooting Tips

• No display? Check wiring and power (use 3.3V, not 5V).
• No address in i2cdetect? Switch SDA/SCL wires.
• Errors? Make sure libr