What the Board Manager Actually Does
The Arduino IDE’s Board Manager is a package installer that downloads and installs hardware support packages — called “cores” — for microcontroller families. A core is a collection of files that teaches the Arduino build system how to compile code for a specific processor: the compiler toolchain binaries, the hardware abstraction library source code (WiFi.h, BLE.h, SPIFFS.h), pre-compiled bootloader blobs, a JSON board descriptor file listing available board variants, and upload tool scripts.
Before installing the ESP32 core, the Arduino IDE can only target AVR microcontrollers (Arduino Uno, Mega, Nano). After installing the ESP32 Espressif core, it gains the ability to compile for the ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C6, and ESP32-H2 — and present all their board variants in the board selection menu.
Adding the ESP32 Board Manager URL
The first step is telling the Arduino IDE where to find the ESP32 core index. Open File → Preferences (macOS: Arduino IDE → Preferences). Find the “Additional boards manager URLs” field at the bottom of the dialog. Click the icon to the right of the field to open the multi-URL editor. Add this URL on its own line:
https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.jsonClick OK. This URL points to a JSON index file that the IDE downloads and parses to show you available core versions and their download locations. The URL itself is just a pointer — no large files are downloaded yet.
If you already have other URLs in this field (for SAM boards, STM32, etc.), add the ESP32 URL on a new line. Multiple URLs are separated by commas or newlines. The order does not matter.
Installing the ESP32 Core
Open the Boards Manager:
- Arduino IDE 2.x: Click the board icon in the left sidebar (looks like a circuit board), or go to Tools → Board → Boards Manager
- Arduino IDE 1.8.x: Go to Tools → Board → Boards Manager
Type esp32 in the search box. You will see “esp32 by Espressif Systems”. Click on it to expand the entry, then click Install. The latest stable version is selected by default — install it. The download is approximately 500 MB and includes the compiler toolchain, all library source files, and pre-compiled blobs. Depending on your internet connection, this takes 5–30 minutes.
Do not close the IDE during installation. A progress bar at the bottom of the IDE window shows download and extraction progress. When “INSTALLED” appears next to the version number, installation is complete.
Verifying the Installation
Go to Tools → Board. You should see a new submenu “ESP32 Arduino” with a long list of supported boards including “ESP32 Dev Module”, “ESP32-S3 Dev Module”, “ESP32-C3 Dev Module”, “AI Thinker ESP32-CAM”, and many more. If this submenu appears, the core is correctly installed.
As a functional verification, select Tools → Board → ESP32 Arduino → ESP32 Dev Module. Select your port (Tools → Port → your COM port). Open File → Examples → WiFi → WiFiScan. Click Upload. If the sketch compiles and uploads successfully, your Board Manager installation is fully operational.
Understanding the Board List
The ESP32 Arduino core includes board definitions for over 100 variants. Most beginners only need a handful:
| Board Selection | Use When |
|---|---|
| ESP32 Dev Module | Generic ESP32 DevKitC, any WROOM-32 board, or unlisted ESP32 boards |
| NodeMCU-32S | NodeMCU-32S boards (CP2102 USB chip, 38 pins) |
| ESP32 Wrover Module | WROVER-based boards — enables PSRAM by default |
| AI Thinker ESP32-CAM | AI-Thinker ESP32-CAM camera boards |
| Adafruit ESP32 Feather | Adafruit HUZZAH32 Feather boards |
| ESP32-S3 Dev Module | ESP32-S3 DevKitC boards and S3-based custom boards |
| ESP32-C3 Dev Module | ESP32-C3 DevKitM and C3-based boards |
| WEMOS D1 MINI ESP32 | LOLIN32 / WEMOS D32 boards |
If your specific board is not listed, use “ESP32 Dev Module” — it is the most generic setting and works for any standard ESP32 WROOM-32 board. The main difference between board definitions is the default flash size, partition scheme, and PSRAM settings. You can override all of these manually under the Tools menu after selecting a board.
Important Tools Settings After Board Selection
After selecting your board, review these settings under the Tools menu:
- CPU Frequency: 240 MHz for maximum performance; 80 MHz for lower power consumption. Most projects use 240 MHz.
- Flash Frequency: 80 MHz is the standard and fastest. Some cheaper flash chips are only rated to 40 MHz — use 40 MHz if you experience random flash-read crashes.
- Flash Size: Must match your board’s actual flash chip. Selecting 4 MB on a board with 2 MB flash will cause the partition table to reference addresses that do not exist, causing boot failures.
- Partition Scheme: “Default 4MB with spiffs” is the standard. “Huge APP (3MB No OTA)” gives more space for the sketch at the cost of OTA capability. “Minimal SPIFFS (1.9MB APP with OTA)” allocates more space to OTA and SPIFFS.
- PSRAM: Enable this if your board has a WROVER module with external PSRAM. Enabling it on a board without PSRAM does not crash the chip but ps_malloc() calls will fail.
- Upload Speed: 921600 for fast uploads. Reduce to 460800 or 115200 if uploads fail.
Managing Multiple Core Versions
You can install multiple versions of the ESP32 core side by side. In the Boards Manager, click the version dropdown before clicking Install to choose a specific version. Old versions remain available even after installing a new one — click the dropdown again and select an older version to “Install” it alongside the newer one. Switch between versions by selecting the desired version in the Boards Manager dropdown. The currently active version for a sketch is whichever was selected when you last compiled it.
Common reason to keep multiple versions: a library you depend on has a known bug fix in v2.0.14 but a regression in v2.0.17. Keep both installed and use v2.0.14 for that specific project while using the latest for new projects.
Troubleshooting Board Manager Issues
Download stalls or fails
Check your internet connection and firewall. The download server is GitHub’s CDN. If you are behind a corporate proxy, configure proxy settings in File → Preferences → Network. Alternatively, download the core ZIP manually from the GitHub releases page and install it using the offline install procedure (copy files to the Arduino15 packages directory).
Boards Manager shows “Error downloading…”
The index URL may be incorrect, or the file at that URL is temporarily unavailable. Verify the URL by opening it in a browser — it should return a JSON file. If the URL is correct, wait a few minutes and try again (GitHub’s CDN occasionally has temporary outages).
Core installed but no ESP32 boards appear in Tools → Board
Restart the Arduino IDE completely. If the issue persists, the installation may be corrupt. Delete the ESP32 packages directory manually: on Windows at %APPDATA%LocalArduino15packagesesp32, on Linux/macOS at ~/.arduino15/packages/esp32. Then reinstall from the Boards Manager.
Compilation error: “xtensa-esp32-elf-g++: not found”
The toolchain binaries are not executable. This can happen if antivirus software quarantined them during download, or if the download was interrupted leaving a partial toolchain. Uninstall the core from Boards Manager and reinstall. On Windows, temporarily pause antivirus software during installation if this recurs.
Keeping the Core Updated
When a new ESP32 core version is released, the Boards Manager shows an “Update” button next to the installed version. Click it to download and install the new version. After updating, recompile and re-test your projects — API changes between versions occasionally require small code adjustments. Espressif documents breaking changes in the MIGRATION_GUIDES directory of the GitHub repository.