Guías · 10 min de lectura

No se instala ESP32 en Arduino IDE: soluciones a cada error

¿No se instala ESP32 en Arduino IDE? URL correcta, Error downloading, tiempo de espera, antivirus y proxy, limpieza de paquetes viejos e instalación offline.

Si no se instala ESP32 en Arduino IDE, estás frente al problema más común al empezar con esta placa: esp32 no aparece en el Gestor de placas, la instalación se detiene a medias con "Error downloading" o, tras varios minutos de espera, termina por tiempo de espera agotado. Casi siempre la causa es una de cinco: una URL del gestor de tarjetas equivocada o vieja, una conexión a internet lenta o restringida, un antivirus que bloquea archivos, descargas viejas que quedaron a medias y restos de paquetes antiguos en el disco.

En esta guía primero harás una instalación limpia paso a paso y luego encontrarás la solución según el mensaje de error que veas en pantalla. También verás cómo instalar sin internet en redes de escuela u oficina con restricciones, cómo obtener información detallada con Arduino CLI y cómo elegir entre los núcleos 2.x y 3.x. Al final, un pequeño programa de prueba confirmará que la instalación de verdad funciona.

Placa de desarrollo ESP32 DevKit
ESP32 DevKit: para programarla en Arduino IDE primero tienes que instalar el paquete de placas de Espressif.

¿Qué es el paquete de placas ESP32 y por qué pesa tanto?

De fábrica, Arduino IDE solo conoce las placas de Arduino. Para el ESP32 necesitas instalar el paquete arduino-esp32 (core) de Espressif. No son unos cuantos archivos: incluye las cadenas de compilación Xtensa y RISC-V, las librerías de ESP-IDF, la herramienta de carga esptool y utilidades de sistema de archivos. Las versiones 3.x actuales descargan cientos de megabytes y, ya descomprimidas, ocupan varios gigabytes en el disco. Entre más grande la descarga, más fácil es que se corte, y de ahí sale la mayoría de los errores.

Instalación correcta paso a paso

  1. Usa la versión 2.x más reciente de Arduino IDE; la base de Java vieja de la 1.8.x a veces no logra abrir conexiones seguras con algunos servidores.
  2. Abre Archivo > Preferencias (en macOS, Arduino IDE > Settings).
  3. En el campo de URLs adicionales del gestor de placas pega esta dirección: https://espressif.github.io/arduino-esp32/package_esp32_index.json. Si ya tienes otras URLs, pon cada una en su propia línea.
  4. Haz clic en Aceptar y espera a que el IDE descargue el índice de paquetes en la parte de abajo.
  5. Abre el Gestor de placas en la barra lateral, escribe esp32 y presiona Instalar en esp32 by Espressif Systems. El paquete "Arduino ESP32 Boards" de Arduino es solo para la Nano ESP32, no los confundas.
  6. Al terminar, elige ESP32 Dev Module o el modelo de tu placa en Herramientas > Placa.
La dirección https://dl.espressif.com/dl/package_esp32_index.json que aparece en tutoriales viejos ya no se actualiza y solo muestra versiones muy antiguas. Si sigue en tu lista, bórrala; tener dos URLs distintas de ESP32 al mismo tiempo revuelve la lista de versiones y puede hacer que fallen las descargas.

Tabla de soluciones según el mensaje de error

Cuando la instalación falla, el panel de Salida en la parte de abajo del IDE muestra un mensaje largo en inglés. No necesitas descifrarlo completo: busca la frase clave en la tabla y aplica la solución que está al lado. Si ves varias, normalmente la última línea es la causa real.

El mensaje diceQué significaSolución
Error downloading ... package_esp32_index.jsonNo se puede llegar al índice de paquetesRevisa la URL letra por letra y ábrela en el navegador; si no carga, el problema es la red o el proxy
context deadline exceeded, Client.Timeout exceeded, DEADLINE_EXCEEDEDLa descarga superó el tiempo límiteAumenta el tiempo de espera, prueba con cable de red o con el hotspot del celular
TLS handshake timeout, x509: certificate signed by unknown authorityNo se pudo crear una conexión seguraCorrige la fecha y hora de la computadora; en una red corporativa, configura el proxy
checksum mismatch, archive hash differs, CRC doesn't matchEl archivo descargado está dañado o incompletoBorra los archivos de ESP32 de la carpeta staging e instala de nuevo
Access is denied, moving extracted archive, renameEl antivirus u otro programa bloqueó un archivoAgrega la carpeta Arduino15 a las exclusiones del antivirus y reinicia el IDE
no space left on deviceEl disco está llenoLibera al menos 5 GB y quita versiones viejas del núcleo
403 Forbidden, 404 Not Found (github.com)GitHub está bloqueado o la dirección es viejaPrueba otra red y actualiza el IDE y la URL
esp32 no aparece en el Gestor de placasFalta la URL o no se actualizó el índiceAgrega la URL y reinicia el IDE

Tiempo de espera agotado y conexión lenta

Lo más común es que la conexión se corte mientras baja uno de los archivos grandes del compilador. Arduino IDE 2.x usa Arduino CLI por dentro, y su tiempo de espera de red por defecto puede quedarse corto en conexiones lentas. Prueba primero lo sencillo: cable de red o el hotspot de tu celular en vez de Wi-Fi, apagar o encender la VPN, o intentar en un horario en que la red esté libre. Si la instalación se cortó, al reiniciarla el IDE no vuelve a bajar los archivos que ya terminaron; con unos cuantos intentos puedes lograrlo.

Si sigue fallando, aumenta el tiempo de espera. Con el IDE cerrado, abre con un editor de texto el archivo .arduinoIDE/arduino-cli.yaml de tu carpeta de usuario, agrega una sección network: y debajo, con sangría, la línea connection_timeout: 600s. Así la espera sube a 10 minutos; el ajuste funciona en las versiones actuales del IDE que traen Arduino CLI 1.x, así que si tu IDE es viejo, actualízalo primero. En redes corporativas, escribe la dirección del proxy en Preferencias > Red dentro del IDE.

Antivirus, firewall y proxy

En Windows, si la instalación se detiene casi al final con "Access is denied" o "moving extracted archive", casi siempre es culpa del antivirus. Al descomprimir el paquete se crean miles de archivos pequeños; Windows Defender u otro programa de seguridad los bloquea para revisarlos y el IDE no puede moverlos a su lugar. La solución es agregar la carpeta Arduino15 a las exclusiones del antivirus mientras instalas; excluir solo esa carpeta es más seguro que apagar la protección por completo. En redes de escuelas y empresas, además, un firewall puede bloquear los servidores de descarga de GitHub. Si el índice de paquetes abre en el navegador pero la instalación sigue fallando, pide al administrador de la red la dirección del proxy, o instala el paquete en casa y pásalo con el método sin internet que verás más abajo.

Sistema operativoCarpeta Arduino15Descargas a medias (staging)
Windows%LOCALAPPDATA%\Arduino15%LOCALAPPDATA%\Arduino15\staging\packages
macOS~/Library/Arduino15~/Library/Arduino15/staging/packages
Linux~/.arduino15~/.arduino15/staging/packages

Cómo limpiar restos de paquetes viejos

Si antes instalaste el ESP32 de otra forma (por ejemplo, a mano desde GitHub) o pusiste una versión vieja hace años, la nueva instalación puede chocar con archivos antiguos. Señales típicas: la instalación termina sin errores pero el ESP32 aparece dos veces en la lista de placas, al compilar salen avisos de "multiple libraries were found" o el IDE se empeña en usar una versión vieja. Con estos pasos empiezas desde cero.

  1. Cierra Arduino IDE por completo.
  2. Borra la carpeta packages/esp32 y el archivo package_esp32_index.json dentro de Arduino15.
  3. Borra los archivos de ESP32 a medias dentro de staging/packages (los que empiezan con esp32-, xtensa-, riscv32- y esptool).
  4. Si en tu carpeta de proyectos (normalmente Documentos/Arduino) hay una carpeta hardware/espressif, quítala también; viene de una instalación manual vieja y choca con la del Gestor de placas.
  5. Abre el IDE, revisa que en Preferencias solo quede la URL actual de ESP32 e instala el paquete otra vez.
En la mayoría de los casos basta con darle una vez a Quitar en el paquete esp32 del Gestor de placas y volver a instalarlo; borra carpetas a mano solo si eso no funciona. Si quieres un respaldo antes, con copiar la carpeta packages dentro de Arduino15 es suficiente.

Instalación sin internet y manual

En un laboratorio escolar con internet limitado o con una conexión muy lenta, lo más confiable es instalar el paquete en una computadora con buen internet y copiarlo. Funciona sin problemas entre dos computadoras con el mismo sistema operativo, porque los compiladores son propios de cada sistema: un paquete instalado en Windows no sirve en macOS.

  1. En la computadora con buen internet, instala Arduino IDE y el paquete ESP32 de la forma normal.
  2. Copia a una memoria USB la carpeta packages/esp32 y el archivo package_esp32_index.json de la carpeta Arduino15 de esa computadora.
  3. En la computadora de destino, abre y cierra Arduino IDE una vez para que se cree la carpeta Arduino15.
  4. Pega lo que copiaste en los mismos lugares de la carpeta Arduino15 de destino y agrega la misma URL de ESP32 en Preferencias.
  5. Abre el IDE; el Gestor de placas mostrará esp32 como instalado y en Herramientas > Placa aparecerán las placas ESP32.

Una segunda opción es bajar con el navegador los archivos que al IDE le cuesta descargar y ponerlos en la carpeta staging/packages. Antes de instalar, el IDE revisa esa carpeta; si el nombre y la suma de verificación coinciden exactamente con el índice de paquetes (package_esp32_index.json), se salta la descarga y descomprime el archivo directo. La línea "Downloading" del panel de Salida te dice qué archivo hace falta. Para desarrolladores hay una tercera vía: clonar el repositorio de GitHub en hardware/espressif dentro de tu carpeta de proyectos, pero este método no debe usarse junto con una instalación del Gestor de placas.

Instalación detallada con Arduino CLI

El IDE solo muestra un mensaje de error corto. Si quieres ver con exactitud en qué archivo y en qué paso falla, puedes hacer lo mismo desde la terminal con Arduino CLI. Como el IDE 2.x ya usa esta herramienta por dentro, un paquete instalado con la CLI también aparece en el IDE mientras ambos usen la misma carpeta de datos.

Comando¿Qué hace?
arduino-cli config initCrea el archivo de configuración
arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.jsonAgrega la URL del paquete ESP32
arduino-cli core update-indexDescarga los índices de paquetes
arduino-cli core install esp32:esp32 -vInstala el paquete ESP32 con salida detallada
arduino-cli core install esp32:[email protected]Instala una versión específica
arduino-cli core listMuestra los núcleos instalados y sus versiones

Cómo elegir la versión correcta del núcleo (core)

El Gestor de placas siempre sugiere la versión más nueva, pero la más nueva no siempre es la mejor para cada proyecto. Con la versión 3.0, arduino-esp32 pasó a la base ESP-IDF 5 y cambió el uso de algunas funciones: para PWM ahora se usa ledcAttach en lugar de ledcSetup y ledcAttachPin, y para temporizadores timerBegin(frecuencia) en lugar de timerBegin(0, 80, true). Por eso una librería o un tutorial viejo escrito para 2.x puede no compilar en 3.x. En el Gestor de placas puedes elegir cualquier versión de la lista que está debajo del paquete; solo queda instalada una versión a la vez.

VersiónBase ESP-IDFChips compatibles¿Cuándo elegirla?
1.0.63.3Solo ESP32Solo para compilar tal cual un proyecto muy viejo
2.0.174.4ESP32, S2, S3, C3Librerías que no se actualizaron a 3.x y tutoriales viejos
3.x (actual)5.xESP32, S2, S3, C3, C6, H2 y más nuevosLa opción por defecto para proyectos y chips nuevos

Si quieres que tu propio código compile en las dos versiones, usa la macro de versión. El ejemplo de abajo enciende suavemente el LED integrado; si ESP_ARDUINO_VERSION_MAJOR vale 3 o más, compila las funciones PWM nuevas y, si no, las viejas. Puedes usar el mismo truco en el código de temporizadores y pines táctiles.

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}

Cómo probar la instalación

No des por hecho que todo funciona solo porque la instalación terminó. Sube el siguiente programa y abre el Monitor Serie a 115200 baudios; verás la versión del núcleo instalado, la versión de ESP-IDF, el modelo del chip y el tamaño de la flash, y el LED integrado parpadeará. Si te salen errores al compilar, el problema sigue siendo la instalación; si la carga termina con "Failed to connect", el problema ya es la placa, el cable o el 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}
Si el ESP32 no aparece en la lista de puertos, lo que falta no es el paquete de placas sino el driver USB; revisa la guía para instalar el driver CH340. Si el código compila pero la carga termina con "Failed to connect", el método del botón BOOT de la guía ESP32 Failed to connect lo resuelve.

¿Todavía no se instala? Lista final de revisión

  • ¿La fecha y la hora están bien? Un reloj equivocado invalida los certificados de las conexiones seguras y todas las descargas fallan.
  • ¿Tu nombre de usuario tiene acentos, ñ o espacios? Algunas herramientas fallan con rutas que llevan letras como á, é o ñ; con el ajuste directories.data de arduino-cli.yaml puedes mover la carpeta de paquetes a una ruta corta como C:\Arduino15.
  • Límite de rutas largas en Windows: las rutas de más de 260 caracteres pueden impedir que el paquete se descomprima; activar las rutas largas en Windows o usar rutas cortas ayuda.
  • Espacio en disco: durante la instalación conviven por un rato los archivos descargados y los descomprimidos, así que deja al menos 5 GB libres.
  • Prueba otra herramienta: si el IDE no lo logra, prueba Arduino CLI y, si tampoco, PlatformIO, que descarga los paquetes de sus propios servidores.
  • Mientras tanto, prueba tu código: hasta resolver la instalación puedes correr tu circuito y tu código en el navegador con el simulador Wokwi.

Una vez que el paquete de placas ESP32 queda bien instalado, pasar a proyectos con Wi-Fi, Bluetooth y sensores toma minutos. Si el ESP32 es nuevo para ti, empieza con ¿Qué es el ESP32?; después, en la app BlueGrays, puedes probar paso a paso los proyectos de encender un LED con ESP32, el LED integrado y la conexión Wi-Fi, con diagrama y código listo.

Preguntas frecuentes

¿Por qué no se instala el paquete ESP32 en Arduino IDE?

Las causas más comunes son una URL del gestor de tarjetas equivocada o vieja, una conexión lenta que agota el tiempo de espera, un antivirus que bloquea archivos y descargas viejas a medias. Primero revisa que la URL sea https://espressif.github.io/arduino-esp32/package_esp32_index.json y luego aplica la solución según el mensaje del panel de Salida.

¿Cuál es la URL correcta del gestor de tarjetas para ESP32?

Para la versión estable actual se usa https://espressif.github.io/arduino-esp32/package_esp32_index.json. La dirección vieja de dl.espressif.com solo muestra versiones muy antiguas; si sigue en tu lista, quítala, porque dos URLs de ESP32 al mismo tiempo pueden dar problemas.

¿Cómo soluciono "Error downloading" en Arduino IDE?

Primero intenta abrir la URL del paquete en el navegador; si no carga, el problema está en la red, el proxy o el firewall. Si carga, borra los archivos a medias de la carpeta staging, revisa la hora de la computadora y vuelve a instalar con cable de red o con el hotspot del celular.

¿Instalo el núcleo ESP32 2.x o 3.x?

Para proyectos nuevos y chips recientes como el ESP32-C6 elige 3.x. Si una librería o tutorial que necesitas se escribió para 2.x y no compila en 3.x, instala la 2.0.17, la última versión 2.x. Puedes cambiar de versión cuando quieras desde la lista del Gestor de placas.

¿Se puede instalar el paquete ESP32 sin internet?

Sí. Instala el paquete en una computadora con internet y el mismo sistema operativo, y copia la carpeta packages/esp32 y el archivo package_esp32_index.json de su carpeta Arduino15 al mismo lugar en la computadora de destino. Al abrir el IDE, el paquete aparece como instalado.

¿Cuánto espacio ocupa el paquete ESP32?

Depende de la versión; las 3.x actuales ocupan varios gigabytes con sus compiladores y librerías. Durante la instalación conviven los archivos comprimidos y los descomprimidos, así que dejar al menos 5 GB libres es un margen seguro.

Ver todos los proyectos
Parpadeo del LED interno del ESP32
ES-4Principiante

Parpadeo del LED interno del ESP32

Parpadeo del LED azul incorporado en el ESP32 DevKit V1. ¡No se necesitan componentes externos! El primer proyecto que debe probar cuando compra un ESP32. GPIO 2 está conectado al LED interno.

4.8(29)
54
LED Parpadeante con ESP32
ES-1Principiante

LED Parpadeante con ESP32

Enseña el uso básico de la salida GPIO con ESP32. Conseguimos un efecto de parpadeo encendiendo y apagando un LED desde el pin digital. Versión para ESP32 del clásico proyecto blink en Arduino UNO; los comandos básicos de blink en el entorno Arduino son los mismos, pero la distribución de pines y los niveles GPIO de 3,3 V del ESP32 difieren de los del Arduino UNO.

4.7(37)
108
Control de LED con pulsador en ESP32 (Push)
ES-2Principiante

Control de LED con pulsador en ESP32 (Push)

El LED se enciende cuando se pulsa el botón y se apaga cuando se suelta. Muestra cómo se utiliza el pin de entrada digital del ESP32 y la resistencia pull-up interna. Gracias al modo INPUT_PULLUP, no se necesita ninguna resistencia externa.

4.6(36)
57
ESP32 Semáforo
ES-5Principiante

ESP32 Semáforo

Simulación de un semáforo real con 3 LED rojo-amarillo-verde. Los tiempos se aproximan a la lógica del tráfico real: rojo largo, amarillo corto, verde largo. Ejemplo clásico de control GPIO secuencial.

4.4(22)
45
Lectura de la intensidad luminosa con el módulo LDR del ESP32
ES-11Principiante

Lectura de la intensidad luminosa con el módulo LDR del ESP32

Visualización en tiempo real en el monitor serie del valor bruto del ADC del módulo LDR y del porcentaje relativo de luz calculado a partir de referencias de oscuridad y claridad. Este porcentaje no es una medición en lux. Explica el funcionamiento de la calibración del módulo. Es recomendable realizarlo antes del Proyecto 10, ya que se utiliza para determinar el valor umbral.

4.6(36)
55
ESP32 LED Fade con PWM
ES-8Principiante

ESP32 LED Fade con PWM

Cambiar el brillo del LED suavemente de 0 a max, de max a 0. Controlamos PWM con analogWrite() como en Arduino - la misma sintaxis con ESP32 Arduino Core 3.0+ funciona sin problemas. Pin definición + pinMode + analogWrite es suficiente.

4.8(36)
55
Conexión Wi-Fi STA con ESP32 (con pantalla LCD)
ES-25Avanzado

Conexión Wi-Fi STA con ESP32 (con pantalla LCD)

En este proyecto, conectamos el ESP32 a la red Wi-Fi doméstica en modo Station (STA) de forma segura y tolerante a fallos. Separamos el SSID y la contraseña en el archivo secrets.h para evitar que se filtren a Git, configuramos un mecanismo de reconexión automática y mostramos el nivel de señal RSSI y la dirección IP en una pantalla LCD I2C. El LED interno actúa como indicador de estado.

4.4(21)
38
Servidor web asíncrono ESP32 (con indicación de IP en la pantalla LCD)
ES-27Avanzado

Servidor web asíncrono ESP32 (con indicación de IP en la pantalla LCD)

En este proyecto, convertimos el ESP32 en un servidor web asíncrono que puedes controlar desde tu teléfono o tu ordenador, siempre que estén conectados a la misma red Wi-Fi. Gracias a la biblioteca ESPAsyncWebServer, el servidor puede procesar varias solicitudes al mismo tiempo (a diferencia del clásico WebServer.h, que se bloquea con una sola solicitud).

4.8(16)
26