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.

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
- Use the latest Arduino IDE 2.x; the old Java stack in 1.8.x sometimes cannot open secure connections to some servers.
- Open File > Preferences (on macOS, Arduino IDE > Settings).
- 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.
- Click OK and wait while the IDE downloads the package index at the bottom of the window.
- 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.
- When it finishes, pick ESP32 Dev Module or your board's model under Tools > Board.
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 contains | What it means | Fix |
|---|---|---|
| Error downloading ... package_esp32_index.json | The package index cannot be reached | Check 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_EXCEEDED | The download hit the time limit | Raise the timeout, try a wired network or a phone hotspot |
| TLS handshake timeout, x509: certificate signed by unknown authority | A secure connection could not be made | Fix your computer's date and time; on a corporate network, enter the proxy settings |
| checksum mismatch, archive hash differs, CRC doesn't match | The downloaded file is corrupt or incomplete | Delete the ESP32 files in the staging folder and install again |
| Access is denied, moving extracted archive, rename | Antivirus or another program locked a file | Add the Arduino15 folder to your antivirus exclusions, then restart the IDE |
| no space left on device | The disk is full | Clear 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 outdated | Try another network and update the IDE and the URL |
| esp32 does not show up in Boards Manager | URL missing or index not refreshed | Add 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 system | Arduino15 folder | Partial 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.
- Close Arduino IDE completely.
- Delete the packages/esp32 folder and the package_esp32_index.json file inside Arduino15.
- Delete the partial ESP32 files in staging/packages (those starting with esp32-, xtensa-, riscv32- and esptool).
- 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.
- Open the IDE, check that only the current ESP32 URL is left in Preferences and install the package again.
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.
- Install Arduino IDE and the ESP32 package the normal way on the computer with good internet.
- Copy the packages/esp32 folder and the package_esp32_index.json file from that computer's Arduino15 folder to a USB stick.
- On the target computer, open and close Arduino IDE once so that the Arduino15 folder is created.
- Paste what you copied into the same places in the target computer's Arduino15 folder and add the same ESP32 URL in Preferences.
- 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.
| Command | What it does |
|---|---|
| arduino-cli config init | Creates the configuration file |
| arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.json | Adds the ESP32 package URL |
| arduino-cli core update-index | Downloads the package indexes |
| arduino-cli core install esp32:esp32 -v | Installs the ESP32 package with verbose output |
| arduino-cli core install esp32:[email protected] | Installs a specific version |
| arduino-cli core list | Lists 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.
| Version | ESP-IDF base | Supported chips | When to choose it |
|---|---|---|---|
| 1.0.6 | 3.3 | ESP32 only | Only to rebuild a very old project as is |
| 2.0.17 | 4.4 | ESP32, S2, S3, C3 | Libraries not yet updated for 3.x and older tutorials |
| 3.x (current) | 5.x | ESP32, S2, S3, C3, C6, H2 and newer | The 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.
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.
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}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.
Projects to build after reading this
See all projects
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.

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.

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.

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.

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.

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.

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.

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.
More articles
BlueGrays app
Build this circuit step by step on your phone
Wiring diagram, code and parts list on one screen. 500+ Arduino, ESP32 and Pico projects ready to build.
Scan with your phone
Point your camera at the code and your phone's app store opens.
or open the store

