Guides · 9 min read

ESP32 Board Manager Not Installing: Fix Arduino IDE Errors

ESP32 board manager not installing in Arduino IDE? Use the right URL and fix Error downloading, timeouts, antivirus, proxy and leftovers, or install offline.

When the ESP32 board manager is not installing in Arduino IDE, you are facing the most common hurdle of getting started with the ESP32: esp32 never shows up in the Boards Manager, the install stops halfway with "Error downloading", or it times out after minutes of waiting. The problem almost always comes from one of five sources: a wrong or outdated Board Manager URL, a slow or restricted internet connection, antivirus software locking files, half-finished old downloads, and leftovers from older packages on your disk.

In this guide you will first do a clean install step by step, then find the fix that matches the error message on your screen. You will also see how to install offline for restricted school and office networks, how to get detailed output with Arduino CLI and how to choose between the 2.x and 3.x cores. Finally, a small test sketch will confirm that the installation really works.

ESP32 DevKit development board
ESP32 DevKit: to program it in Arduino IDE, you first need to install Espressif's board package.

What is the ESP32 board package and why is it so big?

Out of the box, Arduino IDE only knows Arduino's own boards. For the ESP32 you need the arduino-esp32 package (core) from Espressif. It is much more than a few files: it includes the Xtensa and RISC-V compiler toolchains, the ESP-IDF libraries, the esptool upload tool and file system tools. Current 3.x versions download hundreds of megabytes and take up several gigabytes once unpacked. The bigger the download, the more likely it is to be interrupted, and that is where most errors come from.

Clean install, step by step

  1. Use the latest Arduino IDE 2.x; the old Java stack in 1.8.x sometimes cannot open secure connections to some servers.
  2. Open File > Preferences (on macOS, Arduino IDE > Settings).
  3. Paste this address into Additional boards manager URLs: https://espressif.github.io/arduino-esp32/package_esp32_index.json. If you already have other URLs, put each one on its own line.
  4. Click OK and wait while the IDE downloads the package index at the bottom of the window.
  5. Open the Boards Manager from the left sidebar, type esp32 and click Install on esp32 by Espressif Systems. Arduino's own "Arduino ESP32 Boards" package is only for the Nano ESP32, so do not mix them up.
  6. When it finishes, pick ESP32 Dev Module or your board's model under Tools > Board.
The address https://dl.espressif.com/dl/package_esp32_index.json found in older tutorials is no longer updated and only lists very old versions. If it is still in your list, delete it; having two different ESP32 URLs at once mixes up the version list and can make downloads fail.

Fix table by error message

When the install fails, the Output panel at the bottom of the IDE shows a long message. You do not have to decode all of it: find the key phrase in the table below and apply the fix next to it. If you see several, the last line is usually the real cause.

Message containsWhat it meansFix
Error downloading ... package_esp32_index.jsonThe package index cannot be reachedCheck the URL letter by letter and open it in a browser; if it does not load, the problem is your network or proxy
context deadline exceeded, Client.Timeout exceeded, DEADLINE_EXCEEDEDThe download hit the time limitRaise the timeout, try a wired network or a phone hotspot
TLS handshake timeout, x509: certificate signed by unknown authorityA secure connection could not be madeFix your computer's date and time; on a corporate network, enter the proxy settings
checksum mismatch, archive hash differs, CRC doesn't matchThe downloaded file is corrupt or incompleteDelete the ESP32 files in the staging folder and install again
Access is denied, moving extracted archive, renameAntivirus or another program locked a fileAdd the Arduino15 folder to your antivirus exclusions, then restart the IDE
no space left on deviceThe disk is fullClear at least 5 GB of disk space and remove old core versions
403 Forbidden, 404 Not Found (github.com)GitHub is blocked or the address is outdatedTry another network and update the IDE and the URL
esp32 does not show up in Boards ManagerURL missing or index not refreshedAdd the URL and restart the IDE

Timeouts and slow connections

The most common case is the connection dropping while one of the big toolchain files is downloading. Arduino IDE 2.x uses Arduino CLI under the hood, and its default network timeout can be too short for slow links. Try the simple fixes first: a wired connection or your phone's mobile hotspot instead of Wi-Fi, turning a VPN off or on, or trying again when the network is quiet. If an install was interrupted, the IDE does not download finished files again when you restart it, so a few attempts may get you there.

If the problem persists, raise the timeout. With the IDE closed, open .arduinoIDE/arduino-cli.yaml in your user folder with a text editor, add a network: section and, indented below it, the line connection_timeout: 600s. This raises the wait to 10 minutes and works in current IDE versions that ship Arduino CLI 1.x; if your IDE is older, update it first. On corporate networks, enter the required proxy address under Preferences > Network in the IDE.

Antivirus, firewall and proxy

On Windows, an install that stops near the end with "Access is denied" or "moving extracted archive" is usually caused by antivirus software. Unpacking the package creates thousands of small files; Windows Defender or another security tool locks them to scan them, and the IDE cannot move them into place. The fix is to add the Arduino15 folder to your antivirus exclusions during the install; excluding just this folder is safer than turning protection off entirely. On school and company networks, a firewall may also block GitHub's download servers. If the package index opens in your browser but the install still fails, ask the network admin for the proxy address, or install the package at home and move it with the offline method below.

Operating systemArduino15 folderPartial downloads (staging)
Windows%LOCALAPPDATA%\Arduino15%LOCALAPPDATA%\Arduino15\staging\packages
macOS~/Library/Arduino15~/Library/Arduino15/staging/packages
Linux~/.arduino15~/.arduino15/staging/packages

Cleaning up old package leftovers

If you installed the ESP32 another way before (for example manually from GitHub) or added an old version years ago, the new install can clash with old files. Typical signs: the install finishes without errors but ESP32 appears twice in the board list, compiling shows "multiple libraries were found" warnings, or the IDE keeps using an old version. These steps give you a completely clean start.

  1. Close Arduino IDE completely.
  2. Delete the packages/esp32 folder and the package_esp32_index.json file inside Arduino15.
  3. Delete the partial ESP32 files in staging/packages (those starting with esp32-, xtensa-, riscv32- and esptool).
  4. If your sketchbook folder (usually Documents/Arduino) contains a hardware/espressif folder, remove it too; it is left over from an old manual install and clashes with the Boards Manager install.
  5. Open the IDE, check that only the current ESP32 URL is left in Preferences and install the package again.
In most cases, clicking Remove once on the esp32 package in Boards Manager and installing it again is enough; delete folders by hand only if that does not help. If you want a backup first, copying the packages folder inside Arduino15 is all you need.

Offline and manual installation

In a school lab with restricted internet or on a very slow connection, the most reliable route is to install the package on a computer with good internet and copy it over. This works smoothly between two computers running the same operating system, because the compilers are OS-specific: a package installed on Windows will not run on macOS.

  1. Install Arduino IDE and the ESP32 package the normal way on the computer with good internet.
  2. Copy the packages/esp32 folder and the package_esp32_index.json file from that computer's Arduino15 folder to a USB stick.
  3. On the target computer, open and close Arduino IDE once so that the Arduino15 folder is created.
  4. Paste what you copied into the same places in the target computer's Arduino15 folder and add the same ESP32 URL in Preferences.
  5. Open the IDE; Boards Manager will show esp32 as installed, and ESP32 boards will appear under Tools > Board.

A second route is to download the files the IDE struggles with in your browser and put them in the staging/packages folder. Before installing, the IDE checks that folder; if the file name and checksum exactly match the package index (package_esp32_index.json), it skips the download and unpacks the file directly. The "Downloading" line in the Output panel tells you which file is needed. A third route for developers is cloning the GitHub repository into hardware/espressif in your sketchbook, but this method must not be used alongside a Boards Manager install.

Detailed install with Arduino CLI

The IDE only shows a short error message. If you want to see exactly which file and which step fails, you can do the same job from the command line with Arduino CLI. Since IDE 2.x already uses this tool in the background, a package you install with the CLI also shows up in the IDE as long as both use the same data folder.

CommandWhat it does
arduino-cli config initCreates the configuration file
arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.jsonAdds the ESP32 package URL
arduino-cli core update-indexDownloads the package indexes
arduino-cli core install esp32:esp32 -vInstalls the ESP32 package with verbose output
arduino-cli core install esp32:[email protected]Installs a specific version
arduino-cli core listLists installed cores and their versions

Choosing the right core version

Boards Manager always suggests the newest version, but the newest is not always right for every project. With version 3.0, arduino-esp32 moved to ESP-IDF 5 and some functions changed: PWM now uses ledcAttach instead of ledcSetup and ledcAttachPin, and timers use timerBegin(frequency) instead of timerBegin(0, 80, true). That is why an old library or tutorial written for 2.x may not compile on 3.x. In Boards Manager you can pick any version from the drop-down below the package and install it; only one version is installed at a time.

VersionESP-IDF baseSupported chipsWhen to choose it
1.0.63.3ESP32 onlyOnly to rebuild a very old project as is
2.0.174.4ESP32, S2, S3, C3Libraries not yet updated for 3.x and older tutorials
3.x (current)5.xESP32, S2, S3, C3, C6, H2 and newerThe default for new projects and new chips

If you want your own code to build on both versions, use the version macro. The example below fades the onboard LED; if ESP_ARDUINO_VERSION_MAJOR is 3 or higher it compiles the new PWM functions, otherwise the old ones. You can use the same trick for timer and touch pin code.

C++ (Arduino IDE)
1// Hem 2.x hem 3.x çekirdekte derlenen PWM örneği / PWM example that builds on both 2.x and 3.x cores
2const int LED_PIN  = 2;
3const int PWM_FREQ = 5000;     // 5 kHz
4const int PWM_RES  = 8;        // 8 bit: 0-255
5
6void setup() {
7#if ESP_ARDUINO_VERSION_MAJOR >= 3
8  ledcAttach(LED_PIN, PWM_FREQ, PWM_RES);   // 3.x: pin tabanlı API / pin-based API
9#else
10  ledcSetup(0, PWM_FREQ, PWM_RES);          // 2.x: önce kanal kurulur / set up the channel first
11  ledcAttachPin(LED_PIN, 0);
12#endif
13}
14
15void loop() {
16  for (int duty = 0; duty <= 255; duty++) {
17#if ESP_ARDUINO_VERSION_MAJOR >= 3
18    ledcWrite(LED_PIN, duty);               // 3.x: pin numarası / pin number
19#else
20    ledcWrite(0, duty);                     // 2.x: kanal numarası / channel number
21#endif
22    delay(5);
23  }
24}

Testing the installation

Do not assume everything works just because the install finished. Upload the sketch below and open the Serial Monitor at 115200 baud; you will see the installed core version, the ESP-IDF version, the chip model and the flash size, and the onboard LED will blink. If you get errors while compiling, the problem is still the installation; if uploading ends with "Failed to connect", the problem is now the board, the cable or the driver.

C++ (Arduino IDE)
1// ESP32 kart paketi kurulum testi / ESP32 board package install test
2// Seri Monitör: 115200 baud / Serial Monitor: 115200 baud
3
4const int LED_PIN = 2;      // çoğu DevKit'te dahili LED / onboard LED on most DevKits
5
6void setup() {
7  Serial.begin(115200);
8  delay(1000);
9  Serial.printf("Arduino-ESP32 core: %d.%d.%d\n",
10                ESP_ARDUINO_VERSION_MAJOR, ESP_ARDUINO_VERSION_MINOR, ESP_ARDUINO_VERSION_PATCH);
11  Serial.printf("ESP-IDF: %s\n", ESP.getSdkVersion());
12  Serial.printf("Yonga / Chip: %s rev %d, %d cekirdek / cores\n",
13                ESP.getChipModel(), ESP.getChipRevision(), ESP.getChipCores());
14  Serial.printf("Flash: %u MB, CPU: %u MHz\n",
15                (unsigned)(ESP.getFlashChipSize() / (1024 * 1024)), (unsigned)ESP.getCpuFreqMHz());
16  pinMode(LED_PIN, OUTPUT);
17}
18
19void loop() {
20  digitalWrite(LED_PIN, !digitalRead(LED_PIN));   // LED yanıp söner / LED blinks
21  delay(500);
22}
If the ESP32 does not appear in the port list at all, what is missing is the USB driver, not the board package; see the CH340 driver install guide. If the code compiles but uploading ends with "Failed to connect", the BOOT button method in the ESP32 Failed to connect guide does the trick.

Still not installing? Final checklist

  • Are the date and time right? A wrong clock invalidates secure connection certificates, and every download fails.
  • Does your user name contain accented letters or spaces? Some tools fail on paths with accented or non-Latin characters; with the directories.data setting in arduino-cli.yaml you can move the package folder to a short path such as C:\Arduino15.
  • Windows long path limit: paths longer than 260 characters can stop the package from unpacking; enabling long path support in Windows or keeping folder paths short helps.
  • Disk space: downloaded archives and unpacked files sit side by side for a while during the install, so keep at least 5 GB of space available.
  • Try another tool: if the IDE fails, try Arduino CLI, and if that fails too, try PlatformIO, which downloads packages from its own servers.
  • Test your code while you wait: until the install is sorted, you can run your circuit and code in the browser with the Wokwi simulator.

Once the ESP32 board package is installed correctly, moving on to Wi-Fi, Bluetooth and sensor projects takes minutes. If the ESP32 is new to you, start with What is the ESP32?; then, in the BlueGrays app, you can try the ESP32 LED, onboard LED and Wi-Fi connection projects step by step with wiring diagrams and ready-to-use code.

Frequently asked questions

Why won't the ESP32 board package install?

The most common causes are a wrong or outdated Board Manager URL, a slow connection that times out, antivirus software locking files and half-finished old downloads. First check that the URL is https://espressif.github.io/arduino-esp32/package_esp32_index.json, then apply the fix that matches the error message in the Output panel.

What is the correct ESP32 Board Manager URL?

For the current stable release, use https://espressif.github.io/arduino-esp32/package_esp32_index.json. The old dl.espressif.com address only lists very old versions; if it is still in your list, remove it, because two ESP32 URLs at once can cause problems.

How do I fix "Error downloading" in Arduino IDE?

First try opening the package URL in a browser; if it does not load, the problem is your network, proxy or firewall. If it loads, delete the partial files in the staging folder, check your computer's clock and restart the install over a wired connection or a phone hotspot.

Should I install ESP32 core 2.x or 3.x?

Choose 3.x for new projects and newer chips such as the ESP32-C6. If a library or tutorial you rely on was written for 2.x and fails to compile on 3.x, install 2.0.17, the last 2.x release. You can switch versions at any time from the drop-down in Boards Manager.

Can I install the ESP32 package without internet?

Yes. Install the package on a computer with internet that runs the same operating system, then copy the packages/esp32 folder and the package_esp32_index.json file from its Arduino15 folder to the same place on the target computer. When you open the IDE, the package shows up as installed.

How much disk space does the ESP32 package need?

It depends on the version; current 3.x releases take up several gigabytes with their toolchains and libraries. Archives and unpacked files exist side by side during the install, so keeping at least 5 GB of space available is a safe margin.

See all projects
ESP32 Built-in LED Blink
ES-4Beginner

ESP32 Built-in LED Blink

Blinking the built-in blue LED on the ESP32 DevKit V1. No external components required! The first project you should try when you buy an ESP32. GPIO 2 is connected to the built-in LED.

4.8(29)
54
LED Blink with ESP32
ES-1Beginner

LED Blink with ESP32

Teaches basic GPIO output usage with ESP32. We achieve a blinking effect by turning an LED on and off from a digital pin. ESP32 version of the classic blink project on Arduino UNO; the basic blink commands in the Arduino environment are the same, but the ESP32's pin layout and 3.3 V GPIO levels differ from those of the Arduino UNO.

4.7(37)
108
ESP32 LED Control with Push Button (Push)
ES-2Beginner

ESP32 LED Control with Push Button (Push)

The LED lights up when the button is pressed and turns off when released. Shows how the ESP32's digital input pin and internal pull-up resistor are used. The INPUT_PULLUP mode eliminates the need for an external resistor.

4.6(36)
57
ESP32 Traffic Light
ES-5Beginner

ESP32 Traffic Light

Real traffic light simulation with 3 LEDs red-yellow-green. Timings close to real traffic logic: red long, yellow short, green long. Classic example of sequential GPIO control.

4.4(22)
45
Reading Light Intensity with the ESP32 LDR Module
ES-11Beginner

Reading Light Intensity with the ESP32 LDR Module

Real-time monitoring of the LDR module's raw ADC value and relative light percentage calculated from dark and light reference values in the Serial Monitor. This percentage is not a lux measurement. Teaches the module’s calibration logic. It is ideal to complete this before Project 10, as it is used to determine the threshold value.

4.6(36)
55
ESP32 LED Fade with PWM
ES-8Beginner

ESP32 LED Fade with PWM

Smoothly changing the brightness of the LED from 0 to max, from max to 0. We control PWM with analogWrite() as in Arduino - the same syntax as ESP32 Arduino Core 3.0+ works without problems. Pin definition + pinMode + analogWrite is enough.

4.8(36)
55
ESP32 Wi-Fi STA Connection (with LCD Screen)
ES-25Advanced

ESP32 Wi-Fi STA Connection (with LCD Screen)

In this project, we connect the ESP32 to the home Wi-Fi network in Station (STA) mode in a secure, fault-tolerant manner. We store the SSID and password in a separate secrets.h file to prevent leaking to Git, set up an auto-reconnect mechanism, and display the RSSI signal level and IP address on an I2C LCD screen. The internal LED works as a status indicator. It is a production-grade connection manager.

4.4(21)
38
ESP32 Asynchronous Web Server (with IP Display on LCD)
ES-27Advanced

ESP32 Asynchronous Web Server (with IP Display on LCD)

In this project, we’re turning the ESP32 into an asynchronous web server that you can control from your phone or computer on the same Wi-Fi network. Thanks to the ESPAsyncWebServer library, the server can process multiple requests simultaneously (unlike the classic WebServer.h, which blocks on a single request). You’ll be able to open the ESP32’s IP address in a browser and click the ON/OFF buttons (the /on and /off routes) to turn the LED connected to GPIO 5 on and off.

4.8(16)
26