Installation and Setup

The Arduino IDE is the easiest way to start programming an ESP32. It provides a simple code editor, one-click upload, and a serial monitor for debugging. This guide walks you through installation, ESP32 board support setup, and your first test upload.

🔗Step 1: Download Arduino IDE 2.x

Go to the official Arduino website and download Arduino IDE 2.x for your operating system:

https://www.arduino.cc/en/software

Arduino IDE 2.x is available for Windows, macOS, and Linux. Download the installer and follow the standard installation process for your platform.

Note: Arduino IDE 2.x is a major upgrade over the legacy 1.8.x version. It has a modern interface, better autocompletion, and a built-in serial plotter. If you still have Arduino IDE 1.8.x installed, we recommend upgrading to 2.x.

Linux users: You can also install via your package manager or Flatpak, but the official download from Arduino's website is usually the most up-to-date. You may need to add your user to the dialout group to access serial ports:

sudo usermod -a -G dialout $USER

Log out and back in for this to take effect.

🔗Step 2: Add ESP32 board support

The Arduino IDE does not include ESP32 support out of the box. You need to tell it where to find the ESP32 board definitions.

1. Open Arduino IDE
2. Go to File > Preferences (on macOS: Arduino IDE > Preferences)
3. Find the field labeled Additional boards manager URLs
4. Paste this URL:

https://espressif.github.io/arduino-esp32/package_esp32_index.json

If you already have other URLs in this field, click the icon to the right to open a multi-line editor and add the ESP32 URL on a new line.

5. Click OK to save

🔗Step 3: Install the ESP32 board package

1. Open the Boards Manager: click the board icon in the left sidebar, or go to Tools > Board > Boards Manager
2. In the search box, type esp32
3. Find "esp32" by Espressif Systems
4. Click Install

The download is about 300 MB, so it may take a few minutes depending on your internet connection. This package includes all ESP32 variants (ESP32, ESP32-S2, ESP32-S3, ESP32-C3, and more).

🔗Step 4: Connect your ESP32

1. Plug your ESP32 dev board into your computer using a USB cable
2. Wait a moment for your operating system to recognize the device

🔗Troubleshooting: board not detected

If your computer does not recognize the ESP32:

• Try a different USB cable. Many cables are charge-only and do not support data. This is the most common problem.
• Try a different USB port. Some ports (especially through hubs) can be unreliable.
• Check if you need a driver. Most ESP32 boards use one of two USB-to-serial chips:
  • CP2102 -- Drivers usually install automatically on modern operating systems. If not, download from Silicon Labs.
  • CH340 -- Common on budget boards. Download drivers from the WCH website if needed.
• Linux users: Make sure your user is in the dialout group (see Step 1).

🔗Step 5: Select your board and port

1. Go to Tools > Board > esp32 and select "ESP32 Dev Module"

   This is the correct choice for most ESP32-WROOM-32 DevKit boards, regardless of the brand. It works with DOIT DevKit V1, NodeMCU-32S, and similar boards.

2. Go to Tools > Port and select the COM port for your ESP32

   • On Windows, it will be something like COM3, COM4, etc.
   • On macOS, it will be /dev/cu.usbserial-xxxx or /dev/cu.SLAB_USBtoUART
   • On Linux, it will be /dev/ttyUSB0 or /dev/ttyACM0

   If you see multiple ports and are not sure which one is the ESP32, unplug the board, note which ports disappear, then plug it back in.

Tip: You can leave the other board settings at their defaults. The most important settings are already correct: Flash Mode "QIO", Flash Size "4MB", Upload Speed "921600". If you experience upload failures, try reducing the upload speed to "115200".

🔗Step 6: Upload a test sketch

Let's verify everything works by uploading a minimal program.

1. Go to File > New Sketch (or press Ctrl+N)
2. Replace the contents with this code:

void setup() {
  Serial.begin(115200);
  delay(1000);
  Serial.println("ESP32 is working!");
}

void loop() {
  Serial.println("Hello from ESP32");
  delay(2000);
}

3. Click the Upload button (right arrow icon) or press Ctrl+U

You should see the IDE compile the sketch, then upload it to the board. The output panel at the bottom will show progress. A successful upload ends with something like:

Leaving...
Hard resetting via RTS pin...

🔗If upload fails

• "A fatal error occurred: Failed to connect to ESP32" -- Hold down the BOOT button on your ESP32 board while the IDE says "Connecting..." and release it once upload starts. Some boards require this manual boot sequence.
• "Permission denied" on Linux -- Make sure you are in the dialout group and have logged out and back in.
• Timeout errors -- Try a lower upload speed: go to Tools > Upload Speed and select 115200.

🔗Step 7: Open the Serial Monitor

1. Click the Serial Monitor icon (magnifying glass) in the top-right of the IDE, or go to Tools > Serial Monitor
2. Set the baud rate to 115200 (must match Serial.begin(115200) in your code)
3. You should see:

ESP32 is working!
Hello from ESP32
Hello from ESP32
Hello from ESP32

If you see garbled text instead, the baud rate in the Serial Monitor does not match the baud rate in your code. Make sure both are set to 115200.

Congratulations -- your ESP32 development environment is set up and working.

🔗Board settings reference

Here are the default board settings for "ESP32 Dev Module" and when you might change them:

🔗Next steps

Your environment is ready. The next article walks you through writing and understanding your first real ESP32 program -- the classic blink sketch.

Prefer VS Code? Check out the PlatformIO Setup guide as an alternative.