>_ ctrlaltbrian
esp32 beginner 15 min

ESP32: install the toolchain the right way

Set up the Arduino IDE for ESP32 the way that does not break six months from now. Boards manager URLs, USB drivers, and the port detection traps.

Code available for: ESP32 Arduino
Published Aug 25, 2026

Most “how to install the ESP32 board” tutorials stop after the boards manager install. They miss the parts that come back to bite you later: the USB driver that loads on one machine but not another, the port that disappears after a firmware update, the bootloader that gets stuck and needs a manual reset.

This tutorial is the one I wish I had when I started. It is the same five steps every tutorial tells you to do, plus the five fixes for the parts that break later.

What you need

  • An ESP32 dev board. Any variant with a USB port will work. The ESP32-DevKitC and the NodeMCU-32S are the most common picks.
  • A USB cable. Data, not charge-only. The cable that came with your phone charger is probably charge-only. The one that came with a real device is data.
  • A computer. macOS, Windows, or Linux. The install steps differ slightly.

Step 1: install the Arduino IDE

Download the regular Arduino IDE from https://www.arduino.cc/en/software. Not the Web Editor. Not Arduino Create. The standalone IDE you can run offline.

Version 2.x is current. It is faster than 1.x and the board manager works the same way. If you have 1.x installed from a previous project, leave it. The two coexist fine.

Step 2: add the ESP32 board package URL

Open the IDE and go to File >> Preferences (macOS: Arduino >> Preferences). Look for the field labeled Additional boards manager URLs. Paste this:

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

If you already have URLs in the field (e.g. for an Adafruit or STM32 board), click the icon next to the field and add this URL on a new line. The board manager supports multiple URLs.

Click OK.

Step 3: install the ESP32 platform

Tools >> Board >> Boards Manager. Wait for the index to load (this takes 30-60 seconds the first time). Search for esp32. The package you want is esp32 by Espressif Systems. Click Install.

This downloads about 250 MB. Go make coffee. The install takes 2-5 minutes depending on your network.

The version number matters less than you think. Anything 2.x or 3.x is fine. The 1.0.x line is end-of-life and missing a lot of recent boards. If a tutorial says “tested with version X.Y” and you have a different version, the code almost always works anyway.

After install, the IDE needs a full restart. File >> Quit, then reopen. This is the part where the install quietly fails for half of people, and they think the board package did not work.

Step 4: pick your board

Tools >> Board >> esp32. You will see a long list. The right pick:

  • ESP32 Dev Module: the generic pick. Works for most dev boards.
  • ESP32 Wrover Module: if your board has 4 MB or more of PSRAM.
  • NodeMCU-32S: if you have that specific board. Same silicon, slightly different pin assignments in the IDE defaults.
  • ESP32-S3 Dev Module: the newer USB-native boards. You will know if you have one.

If you do not know which, ESP32 Dev Module is the safe default.

Step 5: pick the port

Tools >> Port. The options depend on your OS:

  • macOS: /dev/cu.usbserial-XXXX or /dev/cu.SLAB_USBtoUART
  • Windows: COM3, COM4, etc. The number is not predictable.
  • Linux: /dev/ttyUSB0 or /dev/ttyACM0

If you see nothing, the USB driver is not installed (more on this below).

Pick the port. The IDE remembers it per board, so once you have it set, it sticks.

File >> Examples >> 01.Basics >> Blink. This opens the canonical blink sketch.

Find this line:

int led = LED_BUILTIN;

Replace LED_BUILTIN with the GPIO number for your board’s onboard LED. For most ESP32 dev boards, that is 2. For the ESP32-S3, that is 48. For the ESP32-C3, that is 8.

Upload. The onboard LED should blink at 1 Hz.

If you do not know your board’s LED pin, search for “[your board name] onboard LED pin” in the ESP32 forum. The answer is one search away.

The five things that break later

1. The USB driver does not load on Windows

The ESP32 uses either the CP2102 or the CH340 USB-serial chip, depending on which board you bought. Most modern Windows installs have the driver already. Some do not.

If the port does not show up:

  • Look in Device Manager >> Ports (COM & LPT).
  • An unknown device with a yellow triangle is the ESP32 with no driver.
  • Download the CP2102 driver from Silicon Labs’ site, or the CH340 driver from WCH’s site. Both are free.

On macOS and Linux, the driver is built in. Skip this section.

2. The port disappears after a firmware crash

If you upload a sketch that crashes the USB stack, the port vanishes and the IDE cannot find it. Fix:

  1. Hold the BOOT button on the ESP32.
  2. Press and release the RESET button (still holding BOOT).
  3. Release the BOOT button.
  4. Try uploading again.

This puts the ESP32 in download mode. The port should reappear.

3. The IDE hangs on “Uploading…”

This is the same problem as #2. The ESP32 is not in download mode. Hold BOOT, press RESET, release BOOT, then click Upload.

Some boards have a different boot behavior. The ESP32-S3 has a single button that does both. The S2 has different pins. Check your specific board’s pinout if the standard procedure does not work.

4. The wrong board package version

If a tutorial says “tested with ESP32 Arduino Core 2.0.14” and you have 3.0.x, some examples may behave differently. The library version mismatch usually shows up as compile errors mentioning deprecated APIs.

Two fixes:

  • Update the libraries the tutorial uses. Tools >> Manage Libraries, search for the library, install latest.
  • If the tutorial is too old to work with your board package, downgrade in the Boards Manager (click the version dropdown next to the installed package).

5. The “exit status 1” upload error

This means the upload failed, usually for one of three reasons:

  • Port not selected (or wrong port).
  • Board not selected (or wrong board).
  • The ESP32 is not in download mode (see #2 and #3).

The full error text usually points to which one. Read it. The fix is usually a 5-second adjustment.

What you learned

The 6-step install flow: IDE download, board manager URL, package install, board select, port select, blink-test. Plus the 5 fixes for the parts that go wrong after the install “succeeds.”

The pattern here is the same one you will see for every board: install, configure, test, fix the parts the tutorial author did not warn you about.

When something else breaks

  • Compiles but does nothing on the chip. The right board is not selected. Double-check Tools >> Board.
  • Compiles, uploads, but the LED blinks wrong color or does not blink. The pin number for LED_BUILTIN is wrong for your board. Look up your specific board’s LED GPIO.
  • Sketch compiles for 10 minutes. The first compile on a new ESP32 project takes 1-3 minutes. Subsequent compiles are 10-30 seconds. If it is consistently slow, close and reopen the IDE.

What to build next

  • The next tutorial is GPIO basics (links at the bottom). You will need this working install before you can blink an LED on a pin you picked, not just LED_BUILTIN.
  • The boot pins tutorial is worth reading even if everything works. It explains what the BOOT button actually does, which is the single most useful debugging skill for the ESP32.