OLED Animation Maker OLED Maker
🔰 Beginner · Arduino OLED display

Arduino OLED Display Tutorial: 128x64 I2C Wiring and Example Code

Everything you need to use an OLED display with Arduino: which module to buy, four-wire I2C hookup, the right libraries, copy-paste sketches that work, and fixes for a blank screen.

By Ashish Updated Oct 29, 2026 19 min read Arduino, I2C, SSD1306
📖

A tutorial you can follow

I wrote this for makers. You get the wiring, the code and the mistakes I see most.

🔌

Hardware you already own

It suits SSD1306 and SH1106, and you'll find pin tables where they help.

💻

Code you can paste

Sketches you can upload in Arduino IDE as they are.

✨

A free tool for you

Want more animations? Preview and export them at oledanimationmaker.com.

Arduino OLED display tutorial: examples of pixel art and animations on a 128x64 SSD1306 OLED display Flat technical illustration of an Arduino Uno board wired to a 0.96 inch blue OLED display via colorful jumper cables

This is a beginner-friendly Arduino OLED display tutorial. You'll pick the right module, wire a 0.96" 128×64 I2C SSD1306, install the right libraries, then upload copy-paste sketches that actually work. If your screen's blank, the I2C scanner and troubleshooting sections below usually fix it in a few minutes. I'd start there.

You'll learn how to interface an OLED with Arduino (Uno, Nano, Mega or ESP32), run Hello World text, draw shapes, scroll text, and diagnose the most common failures: a wrong address (0x3C vs 0x3D), wiring mistakes, and a forgotten display.display().

Quick answer: how to connect an OLED display to Arduino. Wire the four pins (VCC to 5V, GND to GND, SDA to A4, SCL to A5 on an Uno or Nano), install Adafruit SSD1306 and Adafruit GFX from the Library Manager, then upload the Hello World sketch with address 0x3C. If the screen stays black, run the I2C scanner. The whole job takes about 20 minutes.

What is a 0.96 inch SSD1306 OLED?

The 0.96-inch SSD1306 OLED is the most common small display for Arduino projects, and you've probably seen one. Resolution is usually 128×64 pixels, though you'll sometimes see 128×32. It talks over I2C with four wires: VCC, GND, SDA, SCL. Its pixels are monochrome (on or off), which looks sharp, and it doesn't use much power.

You'll find blue, white or yellow-blue split variants. The controller may be an SSD1306 or the look-alike SH1106, and the wrong driver gives you a shifted image.

Which OLED display should you buy for Arduino?

Most "OLED display for Arduino" listings are one of five modules. They look alike in photos, so check the size, the pin count and the controller chip named in the listing before you order.

ModulePixelsControllerPinsGood for
0.96" I2C128×64SSD13064 (VCC, GND, SCL, SDA)Your first OLED. Every example on this page targets it.
0.91" I2C bar128×32SSD13064One or two lines of status text in a small case.
1.3" I2C128×64Usually SH11064Bigger, easier to read. Needs an SH1106 driver, see SH1106 vs SSD1306.
0.96" SPI128×64SSD13067 (adds DC, CS, RES)Fast animations and games. See SPI vs I2C.
1.5" square128×128SH1107 or SSD13274 or 7Square dashboards and robot faces. See the SH1107 guide.

If you are not sure, buy the 0.96" 4-pin I2C SSD1306. It needs only two signal wires, works from 3.3 V or 5 V on most modules (check for an onboard regulator), and is the display almost every Arduino library example assumes. Newer batches may carry an SSD1315 chip, which runs the same SSD1306 code. Colour is fixed by the glass: white, blue, or a yellow strip over a blue area. It is not something you set in code.

Step 1: Wire the OLED display to Arduino (I2C pin table)

Use this pin map if you've got a 4-pin I2C OLED module:

OLED pin Arduino Uno / Nano Arduino Mega ESP32
VCC 5V (or 3.3V if marked) 5V / 3.3V 3.3V
GND GND GND GND
SDA A4 20 GPIO 21
SCL A5 21 GPIO 22

The default I2C address is usually 0x3C. You'll find that some 128×64 boards use 0x3D. If your display stays blank, jump to the I2C scanner.

Step 2: Install libraries

In Arduino IDE, you'll go to Sketch → Include Library → Manage Libraries and install:

  • Adafruit GFX Library for text, lines and circles
  • Adafruit SSD1306 as your display driver

Optional: grab U8g2 too if you'd prefer that library later for fonts and animations. My U8g2 tutorial for SSD1306 and SH1106 covers it from the constructor up. No board yet? You can run every sketch on this page in the Wokwi OLED simulator first.

Step 3: Arduino OLED 128x64 I2C Hello World you can copy and paste

Close-up of a monochrome 0.96 inch SSD1306 OLED screen showing Hello World text

This is the sketch you'll want if you searched for an Arduino OLED 128x64 I2C example. Create a new sketch, paste it, pick your board and port, then Upload. If nothing appears, change 0x3C to 0x3D.

#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET    -1
#define SCREEN_ADDRESS 0x3C   // try 0x3D if blank

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);

void setup() {
  Serial.begin(9600);

  if (!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
    Serial.println(F("SSD1306 allocation failed"));
    for (;;); // stop here if OLED not found
  }

  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.println(F("Hello World!"));
  display.println(F("SSD1306 128x64"));
  display.println(F("I2C example"));
  display.display();  // required — nothing shows without this
}

void loop() {
  // static text — nothing to update
}

Here are the key functions you'll reuse: clearDisplay(), setTextSize(), setCursor(x, y), println(), and always display(), which pushes the pixels to your screen.

You can also open the library demo yourself: File → Examples → Adafruit SSD1306 → ssd1306_128x64_i2c Set SCREEN_ADDRESS the same way.

Once Hello World works, my 10 Arduino OLED 128x64 I2C example sketches cover text sizes, live counters, bitmaps, the 128×32 version and ESP32 custom pins, all built on this same setup.

Step 4: I2C scanner (fix blank OLED)

If Hello World fails, don't guess the address. Upload this scanner and open Tools → Serial Monitor at 9600 baud. You should see something like I2C device found at address 0x3C.

#include <Wire.h>

void setup() {
  Wire.begin();
  Serial.begin(9600);
  while (!Serial); // wait on Leonardo / some boards
  Serial.println(F("I2C Scanner"));
}

void loop() {
  byte error, address;
  int nDevices = 0;

  Serial.println(F("Scanning..."));

  for (address = 1; address < 127; address++) {
    Wire.beginTransmission(address);
    error = Wire.endTransmission();

    if (error == 0) {
      Serial.print(F("I2C device found at 0x"));
      if (address < 16) Serial.print('0');
      Serial.println(address, HEX);
      nDevices++;
    }
  }

  if (nDevices == 0) {
    Serial.println(F("No I2C devices found — check SDA/SCL/power"));
  } else {
    Serial.println(F("Done."));
  }

  delay(5000);
}

No devices found? Recheck SDA and SCL, since swapped pins are common, then check your power and ground. On an ESP32, confirm you're using the pins you expect (often 21 and 22).

Step 5: Draw shapes (GFX example)

Once your text works, shapes open the door to dashboards and menus. Paste this after a successful Hello World setup (same includes and display.begin as above):

void setup() {
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    for (;;);
  }

  display.clearDisplay();

  display.drawRect(0, 0, 128, 64, SSD1306_WHITE);   // border
  display.fillRect(10, 10, 40, 20, SSD1306_WHITE);  // filled box
  display.drawCircle(90, 32, 18, SSD1306_WHITE);    // circle
  display.drawLine(0, 63, 127, 0, SSD1306_WHITE);   // diagonal

  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(10, 40);
  display.print(F("GFX shapes"));
  display.display();
}

void loop() {}

If you'd rather lay things out visually than guess coordinates, see the draw OLED shapes guide.

Step 6: Scrolling text example

Hardware scroll is built into Adafruit SSD1306. This sketch shows text, then scrolls it left, so you can watch it work:

void setup() {
  if (!display.begin(SSD1306_SWITCHCAPVCC, 0x3C)) {
    for (;;);
  }

  display.clearDisplay();
  display.setTextSize(2);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 20);
  display.println(F("Scroll me"));
  display.display();

  display.startscrollleft(0x00, 0x0F); // scroll full display
}

void loop() {
  // hardware scroll runs until stopscroll()
}

For custom motion with sensors or menus, I'd move the X cursor yourself and use millis() instead of delay(), so your board stays responsive.

Step 7: Images and animations (your next step)

Static logos use drawBitmap() with a PROGMEM byte array, and that's easy. Multi-frame animations are tedious by hand. Convert your frames once, then play them in a loop. I've written dedicated guides:

Troubleshooting: when your OLED is blank or garbled

  • Completely blank. You probably have the wrong I2C address, so run the scanner. Check your SDA, SCL and power too.
  • Garbled or shifted image. You likely have an SH1106 running SSD1306 code. See SH1106 vs SSD1306.
  • Flicker. Call display.display() only when your content changes.
  • "SSD1306 allocation failed". Your display isn't responding. Check the wiring or address.
  • Code uploads but nothing shows. You forgot display.display().

Faster path: generate animations in the browser

When you're ready for multi-frame animations and not just Hello World, use the free OLED animation maker to preview frames and export Adafruit SSD1306, U8g2 or MicroPython code.

Next: animate your OLED without hand-writing arrays

You get 100+ templates, GIF import, WebSerial preview and SSD1306 & SH1106 support

Open oledanimationmaker.com →

Arduino OLED display FAQ

What is the best OLED display for Arduino?

For most projects, the 0.96" 128×64 I2C module with an SSD1306 chip. It is cheap, needs only four wires and works with the Adafruit SSD1306 and U8g2 libraries. Pick a 1.3" SH1106 if you need larger text, or an SPI module for fast animation.

Can I connect an OLED display to Arduino without a breadboard?

Yes. A 4-pin I2C OLED plugs straight into the Uno with four female-to-male jumper wires: VCC to 5V, GND to GND, SDA to A4 and SCL to A5. No resistors are needed, because the module already has its pull-ups.

Which pins do I use for an I2C OLED on Arduino Uno?

You wire SDA → A4, SCL → A5, VCC → 5V and GND → GND.

Why is my Arduino OLED blank?

Try address 0x3D instead of 0x3C, run the I2C scanner, and make sure you call display.display().

What's the I2C address of my 0.96" SSD1306?

It's usually 0x3C, though some 128×64 modules use 0x3D. Your scanner will confirm it.

What libraries do I need?

You need Adafruit SSD1306 and Adafruit GFX, both from Library Manager.

SSD1306 vs SH1106: which one do I have?

See our SH1106 vs SSD1306 guide. The wrong driver gives you a shifted image.

Where do I connect SDA and SCL on an ESP8266 NodeMCU?

D2 is SDA (GPIO4) and D1 is SCL (GPIO5). Power the module from 3.3V and call Wire.begin(D2, D1) before display.begin. If your Uno sketch only uses A4 and A5, it'll upload and then show a black panel on NodeMCU.

What does OLED_RESET -1 mean in your Hello World sketch?

It means you've got no Arduino pin connected to RES. Four-pin I2C boards tie reset on the PCB, so pass -1. If you pass a GPIO and that pin sits low, the chip can ACK on the scanner and the glass stays black.

I have a 128×32 module. Why is the text cut in half?

Your constructor height must be 32, not 64: Adafruit_SSD1306 display(128, 32, &Wire, -1). A 64-pixel buffer on a 32-pixel panel draws past the glass. The I2C address is still usually 0x3C.

begin() prints allocation failed on my Uno, and it scanned 0x3C. What now?

Your bus works, so either the 1024-byte framebuffer didn't fit or begin used the wrong address. Check Tools → Board, drop a second display object, and match 0x3C or 0x3D. On an ESP32 this SRAM error is rare. On an Uno, two full displays take about 2 KB and often won't allocate.

Build a three-line status screen that updates on a timer

Hello World proves your wires. The sketch my students actually keep is a small status block: a title, a sensor line and a one-line hint, redrawn twice a second so I2C isn't busy the rest of the time. It uses the same constructor as Step 3: 128×64, reset -1, and address 0x3C unless your scanner printed 0x3D.

uint32_t lastDraw = 0;

void drawStatus(int tempC, bool heaterOn) {
  display.clearDisplay();
  display.setTextSize(1);
  display.setTextColor(SSD1306_WHITE);
  display.setCursor(0, 0);
  display.print(F("Bench status"));
  display.drawLine(0, 10, 127, 10, SSD1306_WHITE);

  display.setTextSize(2);
  display.setCursor(0, 16);
  display.print(tempC);
  display.print(F(" C"));

  display.setTextSize(1);
  display.setCursor(0, 44);
  display.print(heaterOn ? F("Heater ON") : F("Heater idle"));
  display.setCursor(0, 56);
  display.print(F("I2C 0x3C"));
  display.display();
}

void loop() {
  if (millis() - lastDraw < 500) return;
  lastDraw = millis();
  int tempC = 24;          // replace with your sensor
  bool heaterOn = tempC < 22;
  drawStatus(tempC, heaterOn);
}

Call drawStatus once at the end of setup, so the glass isn't blank until the first 500 ms elapses. That 500 ms gap is the whole lesson. display() sends the 1024-byte frame every time, and a text UI doesn't need that any faster. I2C at the default speed is the right bus here. You'd reach for SPI when a later project replaces this text with a high frame-rate bitmap loop, not for three lines of status.

Size 2 digits are 12 pixels wide. "24 C" fits. A long sentence at size 2 will run off x=127, because setTextWrap is on by default and the next line may collide with "Heater idle." Keep size 2 for the number and size 1 for sentences. If your number's faint, set contrast once after begin: display.ssd1306_command(SSD1306_SETCONTRAST); then display.ssd1306_command(0xCF);. Contrast 0x00 looks like your sketch never ran.

Failures after your Hello World already worked

  • Scanner prints 0x3C, your sketch still says allocation failed. Either begin is pointed at 0x3D, or your Uno is out of SRAM because two Adafruit_SSD1306 objects each want a 1024-byte buffer. Match the address, and keep one display object.
  • Text worked yesterday, black today, scanner sometimes empty. Your Dupont plug isn't seated, or two pull-up pairs are fighting. Module boards usually include 4.7k on SDA and SCL. A second sensor with its own 4.7k can make a long jumper fail. Unplug the other device. Move the OLED to a new breadboard row. Don't add another resistor "to be safe." You'd only make it worse.
  • The back of your PCB says 0x78. That's the 8-bit write address, and begin() wants 0x3C. The solder jumper or address resistor that selects 0x78 versus 0x7A is how you pick 0x3C versus 0x3D. If you type 0x78 into your sketch, it never matches the scanner.
  • Everything's shifted about two columns. Your chip is an SH1106, 132×64 internally, and the SSD1306 constructor doesn't apply the column offset. Switch library constructors. The pin table doesn't change.
  • ESP32 upload succeeds, scanner finds nothing. Your wires are on A4-style pins, or you powered the module from 5 V so its pull-ups pull GPIO21 and GPIO22 too high. Use GPIO21 (SDA), GPIO22 (SCL) and 3.3 V, then Wire.begin(21, 22) before begin.
  • Picture updates only after you wiggle SCL. That's breadboard contact, not a software scroll bug, so don't rewrite your code. Solder the four wires if your display is leaving the bench. A cold joint on the module header feels identical.

Pin and power differences that'll break a copied sketch

The Step 1 table is the wiring. These are the mistakes that remain once you've read the table and the board on your desk is no longer an Uno.

BoardSDA / SCLCall this before beginOLED VCC
Uno / NanoA4 / A5Wire.begin() is enough5V
Mega 256020 / 21Wire.begin() if Tools → Board is Mega5V
ESP32GPIO21 / GPIO22Wire.begin(21, 22)3.3V
ESP8266 NodeMCUD2 / D1Wire.begin(D2, D1)3.3V

A Leonardo is different again (SDA on digital 2, SCL on digital 3), and your scanner sketch should keep while (!Serial) or you'll miss the address print. If Tools → Board doesn't match the silicon, Wire.begin() talks on the wrong pins and your OLED looks dead. Reset stays -1 on all of these 4-pin modules.

A 128×64 frame buffer is 1024 bytes on every one of these boards. An Uno feels that in SRAM, but an ESP32 doesn't. The pixels and the I2C address don't get larger on a faster board. Once you've outgrown text and you're pushing full bitmaps many times a second, you'll want the SPI versus I2C comparison, not the Hello World on this page.

Related tutorials

Free tools: OLED Animation Maker for your SSD1306 and SH1106 animations, Assemble Studio for your name and logo animations, the Shadow Box Lamp Generator for your 3D-printed shadow lamps, Text to STL for your 3D-printed names and keychains, and 3MF to Web to show your 3D prints on any website. New: the OLED Block Coder for drag and drop OLED programs and games, the Image to Byte Array converter, the OLED Robot Eyes generator and the Lithophane Maker. See all tools.