WLED Install ESP32 ESP8266 Firmware Getting Started WLED Max How-To

How to Install WLED on an ESP32 or ESP8266: Web Installer, Drivers and esptool

Flash WLED onto a bare ESP32, S3, C3 or ESP8266: the web installer step by step, which build to pick, USB drivers, esptool, and fixes when it fails.

By

Quick answer: plug the board into a computer with a USB cable that carries data, open install.wled.me in Chrome or Edge on a computer, click Install, pick the board’s port and wait about a minute. The installer picks the right build for your chip. Then join the WLED-AP Wi-Fi (password wled1234), or let the installer connect the board to your Wi-Fi directly. Safari and phones can’t flash. The WLED docs also list Opera and Firefox 151 or newer.

Most controllers sold “with WLED” (QuinLED, Athom, GLEDOPTO and others) arrive with WLED installed. Skip to the Wi-Fi setup guide if yours lights up and shows a WLED-AP network. This page is for bare boards, and for boards you want to reinstall from scratch.

What you need

  • A board. An ESP32 is the better choice today: more memory, more LED outputs, and every WLED 16 feature, including all of the new particle effects. An ESP8266 (Wemos D1 mini, NodeMCU) still works for one strip of a few hundred LEDs.
  • A USB cable that carries data. Many cables that came with a gadget only charge. If no port shows up, try another cable before anything else.
  • Chrome or Edge on Windows, macOS, Linux or ChromeOS. The installer talks to the board through the browser’s serial port support. The WLED docs also list Opera and Firefox 151 or newer. Safari doesn’t have it, and neither do phones.

Which chip do you have?

The installer detects the chip, but it helps to know for drivers and later updates. Look at the metal shield on the board.

Marking on the moduleChipCommon boards
ESP-12F, ESP-12E, ESP8266EXESP8266Wemos D1 mini, NodeMCU
ESP32-WROOM-32, ESP32-WROVERESP32 (classic)ESP32 DevKit, D1 mini32, QuinLED Dig boards
ESP32-S3ESP32-S3S3 DevKit, many new controllers
ESP32-C3ESP32-C3C3 mini and “super mini” boards
ESP32-S2ESP32-S2Lolin S2 mini

USB chip and drivers. Boards with a separate USB chip (most ESP8266 and classic ESP32 boards) use a CH340/CH34x or a CP2102. On Windows these often need a driver before a port appears; the installer page links both. macOS and Linux usually see the port right away. S2, S3 and C3 boards with USB built into the chip need no driver.

Install with the web installer

  1. Plug in the board and open install.wled.me.
  2. Pick a version. Take the newest stable release (WLED 16.0.1 at the time of writing), not a nightly or beta.
  3. Pick a build type. Plain fits almost everyone; on WLED 16 the regular ESP32 and ESP8266 release builds already include the sound reactive features. Ethernet is for controllers with a network jack.
  4. Leave the mode on Basic unless you know your board’s flash size and memory (see which build below).
  5. Click Install, choose the board’s port in the browser’s list and confirm.
  6. Wait for the progress to reach 100 percent and the board to restart. It takes a minute or two.

After the install, the installer can usually send your Wi-Fi name and password to the board straight away. If it offers that, do it: the board joins your network and you skip the hotspot step. Otherwise, the board starts its own WLED-AP network and the Wi-Fi setup guide takes it from there.

First settings after the install

A fresh WLED doesn’t know your LEDs yet. It assumes 30 WS2812B LEDs on one data pin: GPIO 2 on ESP8266 and ESP32-C3, GPIO 16 on other ESP32 boards, GPIO 4 on the Ethernet build. Before connecting a long strip:

  1. Open Config›LED & Hardware (LED Preferences on 0.15 and older).
  2. Set the data GPIO your strip is wired to, the LED type (WS281x for most strips) and the length.
  3. Set Maximum PSU Current to what your power supply can deliver. This keeps the strip from drawing more than the supply can give at full white.
  4. If red shows as green, change the color order (GRB is the most common; many 12 V pixel strings are RGB).

The settings that matter most, with real numbers, are in WLED settings explained.

Which build for which board

The web installer picks the chip for you. When you download a file yourself (for esptool, or to update over Wi-Fi later), the name has to match the board. From the WLED 16.0.1 release:

FileFor
WLED_16.0.1_ESP32.binClassic ESP32 with 4 MB flash, the usual DevKit
WLED_16.0.1_ESP32_Ethernet.binESP32 controllers with an Ethernet jack
WLED_16.0.1_ESP32_WROVER.binESP32 WROVER modules with PSRAM
WLED_16.0.1_ESP32-S3_8MB_opi.bin and the other S3 filesESP32-S3, by flash size and PSRAM type (opi, qspi or none)
WLED_16.0.1_ESP32-C3.bin, -C3-QIO.binESP32-C3. Try the QIO file (in the installer: Advanced, Flash mode QIO) if the plain one doesn’t start
WLED_16.0.1_ESP32-S2.binESP32-S2
WLED_16.0.1_ESP8266.binESP8266 with 4 MB flash (D1 mini, NodeMCU)
WLED_16.0.1_ESP02.binESP8266 with 2 MB flash
WLED_16.0.1_ESP01.binESP8266 with 1 MB flash (ESP-01, many smart plugs and bulbs). No updates over Wi-Fi

Two things trip people up:

  • ESP32-S3 with PSRAM. Boards sold as N8R8 or N16R8 have octal (OPI) PSRAM. The installer’s Advanced mode has a Memory setting for it. A build without PSRAM support still runs on such a board, it just doesn’t use the extra memory. A PSRAM build on a board without that kind of PSRAM won’t start.
  • Small flash. For 1 MB and 2 MB boards, switch the installer to Advanced and pick Flash size 1MB or 2MB; it then installs the ESP01 or ESP02 build. If that fails, use esptool (below) with the ESP01 or ESP02 file.

Later updates go over Wi-Fi from the web UI or an app, and the build name you installed matters then too. The firmware update guide explains it.

Install with esptool (any board, any flash size)

esptool is the command line flasher the web installer is built on. Install it with pip install esptool, download the right file from the WLED releases page on GitHub, and connect only one board.

ESP8266, the whole image at address 0:

esptool.py write-flash 0x0 ./WLED_16.0.1_ESP8266.bin

Classic ESP32: the bootloader once (the WLED docs link esp32_bootloader_v4.bin), then the firmware at 0x10000:

esptool.py write-flash 0x0 ./esp32_bootloader_v4.bin
esptool.py write-flash 0x10000 ./WLED_16.0.1_ESP32.bin

Add --port COM3 (Windows) or --port /dev/ttyUSB0 (Linux) when esptool picks the wrong port. Older esptool versions spell the commands write_flash and erase_flash.

If a board misbehaves after flashing, erase it completely and flash again: esptool.py erase-flash. That also deletes all WLED settings and presets on it, so back them up first if the board ran WLED before.

When it doesn’t work

What you seeWhat to do
No port in the listAnother cable (data, not charge only). On Windows, install the CH340 or CP2102 driver. Try another USB port, not a hub
“Failed to initialize” or stuck on “Connecting”Hold the BOOT button, click Install, and let go when the progress starts. Some boards also need EN/RST pressed once while BOOT is held
Stuck on “Preparing installation”An ad blocker, VPN or firewall is blocking the firmware download. Turn it off for the page, or download the file and use esptool
Install finished, no WLED-AP appearsWait 30 seconds. Then press the board’s reset button. On C3 boards try the QIO build (Advanced, Flash mode QIO), on S3 boards the build that matches your flash and PSRAM
WLED-AP appears, then the board keeps restartingOften the power: a long strip powered from the USB port. Disconnect the LEDs and check the board alone
ESP8266 with 1 or 2 MB flashInstaller in Advanced mode, Flash size 1MB or 2MB. If that fails, esptool with the ESP01 or ESP02 file

Once WLED runs and the light is on your Wi-Fi, set up the new device, then try effects with previews.

FAQ

Can I install WLED from my phone? Not the first install. The web installer needs a desktop browser such as Chrome or Edge on a computer with USB. After that, updates go over Wi-Fi from any phone.

Is WLED free? Yes. WLED is open source, and the installer and all builds are free.

ESP32 or ESP8266 for WLED? ESP32 for anything new. It has more memory and outputs and gets every new feature. The ESP8266 is fine for a single strip of a few hundred LEDs.

Will installing WLED erase my settings? A fresh install over a different firmware does. Reinstalling WLED over WLED with the web installer usually keeps them, but back up the configuration and presets first to be safe.

Do I need a special build for music? Not on WLED 16. Its regular release builds (except ESP01 and the small ESP02 min build) include AudioReactive; you switch it on under Usermods. Without a microphone on the board, your phone can be the microphone (how).