Pacote de placas ESP32 não instala: como resolver os erros na Arduino IDE
O pacote de placas ESP32 não instala na Arduino IDE? Use a URL certa e resolva Error downloading, tempo limite, antivírus, proxy e restos de pacotes antigos, ou instale offline.
Quando o pacote de placas ESP32 não instala na Arduino IDE, você está diante do obstáculo mais comum de quem começa com o ESP32: o esp32 nunca aparece no Gerenciador de Placas, a instalação para no meio com “Error downloading” ou estoura o tempo limite depois de minutos de espera. O problema quase sempre vem de uma destas cinco fontes: uma URL do Gerenciador de Placas errada ou desatualizada, uma conexão de internet lenta ou restrita, um antivírus travando arquivos, downloads antigos que ficaram pela metade e restos de pacotes mais antigos no disco.
Neste guia você vai primeiro fazer uma instalação limpa, passo a passo, e depois encontrar a solução que corresponde à mensagem de erro na sua tela. Também vai ver como instalar offline em redes restritas de escolas e escritórios, como obter uma saída detalhada com o Arduino CLI e como escolher entre os cores 2.x e 3.x. Por fim, um pequeno sketch de teste confirma que a instalação funciona de verdade.

O que é o pacote de placas ESP32 e por que ele é tão grande?
Recém-instalada, a Arduino IDE só conhece as placas da própria Arduino. Para o ESP32 você precisa do pacote (core) arduino-esp32, da Espressif. Ele é muito mais do que alguns arquivos: inclui as toolchains de compilação Xtensa e RISC-V, as bibliotecas do ESP-IDF, a ferramenta de gravação esptool e ferramentas de sistema de arquivos. As versões 3.x atuais baixam centenas de megabytes e ocupam vários gigabytes depois de descompactadas. Quanto maior o download, maior a chance de ele ser interrompido, e é daí que vem a maioria dos erros.
Instalação limpa, passo a passo
- Use a versão 2.x mais recente da Arduino IDE; a base Java antiga da 1.8.x às vezes não consegue abrir conexões seguras com alguns servidores.
- Abra Arquivo > Preferências (no macOS, Arduino IDE > Configurações).
- Cole este endereço no campo URLs do Gerenciador de Placas Adicionais: https://espressif.github.io/arduino-esp32/package_esp32_index.json. Se você já tiver outras URLs, coloque cada uma em uma linha.
- Clique em OK e espere a IDE baixar o índice de pacotes, na parte de baixo da janela.
- Abra o Gerenciador de Placas na barra lateral esquerda, digite esp32 e clique em Instalar em esp32 by Espressif Systems. O pacote “Arduino ESP32 Boards”, da própria Arduino, serve só para o Nano ESP32; não confunda os dois.
- Quando terminar, escolha ESP32 Dev Module ou o modelo da sua placa em Ferramentas > Placa.
Tabela de soluções por mensagem de erro
Quando a instalação falha, o painel Saída, na parte de baixo da IDE, mostra uma mensagem comprida. Você não precisa decifrar tudo: encontre a expressão-chave na tabela abaixo e aplique a solução ao lado. Se aparecerem várias, a última linha costuma ser a causa real.
| A mensagem contém | O que significa | Solução |
|---|---|---|
| Error downloading ... package_esp32_index.json | Não é possível acessar o índice de pacotes | Confira a URL letra por letra e abra-a em um navegador; se ela não carregar, o problema é a sua rede ou o proxy |
| context deadline exceeded, Client.Timeout exceeded, DEADLINE_EXCEEDED | O download estourou o tempo limite | Aumente o tempo limite, tente uma rede cabeada ou o hotspot do celular |
| TLS handshake timeout, x509: certificate signed by unknown authority | Não foi possível estabelecer uma conexão segura | Acerte a data e a hora do computador; em rede corporativa, informe as configurações de proxy |
| checksum mismatch, archive hash differs, CRC doesn't match | O arquivo baixado está corrompido ou incompleto | Apague os arquivos do ESP32 na pasta staging e instale de novo |
| Access is denied, moving extracted archive, rename | O antivírus ou outro programa travou um arquivo | Adicione a pasta Arduino15 às exclusões do antivírus e reinicie a IDE |
| no space left on device | O disco está cheio | Libere pelo menos 5 GB de espaço em disco e remova versões antigas do core |
| 403 Forbidden, 404 Not Found (github.com) | O GitHub está bloqueado ou o endereço está desatualizado | Tente outra rede e atualize a IDE e a URL |
| O esp32 não aparece no Gerenciador de Placas | Falta a URL ou o índice não foi atualizado | Adicione a URL e reinicie a IDE |
Tempo limite e conexões lentas
O caso mais comum é a conexão cair enquanto um dos arquivos grandes da toolchain está sendo baixado. A Arduino IDE 2.x usa o Arduino CLI por baixo dos panos, e o tempo limite de rede padrão dele pode ser curto demais para conexões lentas. Tente primeiro as soluções simples: uma conexão cabeada ou o hotspot do celular em vez do Wi-Fi, desligar ou ligar a VPN, ou tentar de novo quando a rede estiver tranquila. Se uma instalação foi interrompida, a IDE não baixa de novo os arquivos já concluídos quando você a reinicia, então algumas tentativas podem bastar para chegar lá.
Se o problema continuar, aumente o tempo limite. Com a IDE fechada, abra .arduinoIDE/arduino-cli.yaml, na sua pasta de usuário, em um editor de texto, acrescente uma seção network: e, indentada abaixo dela, a linha connection_timeout: 600s. Isso aumenta a espera para 10 minutos e funciona nas versões atuais da IDE, que trazem o Arduino CLI 1.x; se a sua IDE for mais antiga, atualize-a antes. Em redes corporativas, informe o endereço de proxy exigido em Preferências > Rede, na IDE.
Antivírus, firewall e proxy
No Windows, uma instalação que para perto do fim com “Access is denied” ou “moving extracted archive” costuma ser culpa do antivírus. Descompactar o pacote cria milhares de arquivos pequenos; o Windows Defender ou outra ferramenta de segurança trava esses arquivos para examiná-los, e a IDE não consegue movê-los para o lugar. A solução é adicionar a pasta Arduino15 às exclusões do antivírus durante a instalação; excluir só essa pasta é mais seguro do que desligar a proteção por completo. Em redes de escolas e empresas, um firewall também pode bloquear os servidores de download do GitHub. Se o índice de pacotes abre no navegador, mas a instalação continua falhando, peça o endereço do proxy ao administrador da rede, ou instale o pacote em casa e leve-o com o método offline descrito mais abaixo.
| Sistema operacional | Pasta Arduino15 | Downloads parciais (staging) |
|---|---|---|
| Windows | %LOCALAPPDATA%\Arduino15 | %LOCALAPPDATA%\Arduino15\staging\packages |
| macOS | ~/Library/Arduino15 | ~/Library/Arduino15/staging/packages |
| Linux | ~/.arduino15 | ~/.arduino15/staging/packages |
Limpeza de restos de pacotes antigos
Se você já instalou o ESP32 de outro jeito (por exemplo, manualmente pelo GitHub) ou adicionou uma versão antiga anos atrás, a nova instalação pode entrar em conflito com arquivos velhos. Sinais típicos: a instalação termina sem erros, mas o ESP32 aparece duas vezes na lista de placas; a compilação mostra avisos “multiple libraries were found”; ou a IDE insiste em usar uma versão antiga. Estes passos garantem um começo totalmente limpo.
- Feche a Arduino IDE por completo.
- Apague a pasta packages/esp32 e o arquivo package_esp32_index.json dentro da Arduino15.
- Apague os arquivos parciais do ESP32 em staging/packages (os que começam com esp32-, xtensa-, riscv32- e esptool).
- Se a sua pasta do sketchbook (normalmente Documentos/Arduino) tiver uma pasta hardware/espressif, remova-a também; ela sobrou de uma instalação manual antiga e entra em conflito com a instalação feita pelo Gerenciador de Placas.
- Abra a IDE, confira se só a URL atual do ESP32 ficou em Preferências e instale o pacote de novo.
Instalação offline e manual
Em um laboratório de escola com internet restrita ou em uma conexão muito lenta, o caminho mais confiável é instalar o pacote em um computador com internet boa e copiá-lo para o outro. Isso funciona sem sustos entre dois computadores com o mesmo sistema operacional, porque os compiladores são específicos de cada sistema: um pacote instalado no Windows não roda no macOS.
- Instale a Arduino IDE e o pacote ESP32 do jeito normal no computador com internet boa.
- Copie a pasta packages/esp32 e o arquivo package_esp32_index.json da pasta Arduino15 desse computador para um pen drive.
- No computador de destino, abra e feche a Arduino IDE uma vez, para que a pasta Arduino15 seja criada.
- Cole o que você copiou nos mesmos lugares da pasta Arduino15 do computador de destino e adicione a mesma URL do ESP32 em Preferências.
- Abra a IDE; o Gerenciador de Placas vai mostrar o esp32 como instalado, e as placas ESP32 vão aparecer em Ferramentas > Placa.
Um segundo caminho é baixar pelo navegador os arquivos em que a IDE empaca e colocá-los na pasta staging/packages. Antes de instalar, a IDE confere essa pasta; se o nome do arquivo e o checksum baterem exatamente com o índice de pacotes (package_esp32_index.json), ela pula o download e descompacta o arquivo direto. A linha “Downloading” do painel Saída mostra qual arquivo é necessário. Um terceiro caminho, para desenvolvedores, é clonar o repositório do GitHub em hardware/espressif, no seu sketchbook, mas esse método não pode ser usado junto com uma instalação pelo Gerenciador de Placas.
Instalação detalhada com o Arduino CLI
A IDE só mostra uma mensagem de erro curta. Se você quiser ver exatamente em que arquivo e em que etapa a instalação falha, dá para fazer o mesmo trabalho pela linha de comando, com o Arduino CLI. Como a IDE 2.x já usa essa ferramenta em segundo plano, um pacote instalado pelo CLI também aparece na IDE, desde que os dois usem a mesma pasta de dados.
| Comando | O que faz |
|---|---|
| arduino-cli config init | Cria o arquivo de configuração |
| arduino-cli config add board_manager.additional_urls https://espressif.github.io/arduino-esp32/package_esp32_index.json | Adiciona a URL do pacote ESP32 |
| arduino-cli core update-index | Baixa os índices de pacotes |
| arduino-cli core install esp32:esp32 -v | Instala o pacote ESP32 com saída detalhada |
| arduino-cli core install esp32:[email protected] | Instala uma versão específica |
| arduino-cli core list | Lista os cores instalados e as respectivas versões |
Como escolher a versão certa do core
O Gerenciador de Placas sempre sugere a versão mais nova, mas a mais nova nem sempre é a certa para todo projeto. Na versão 3.0, o arduino-esp32 passou para o ESP-IDF 5 e algumas funções mudaram: o PWM agora usa ledcAttach no lugar de ledcSetup e ledcAttachPin, e os timers usam timerBegin(frequency) no lugar de timerBegin(0, 80, true). É por isso que uma biblioteca ou um tutorial antigo, escrito para a 2.x, pode não compilar na 3.x. No Gerenciador de Placas, você pode escolher qualquer versão na lista suspensa abaixo do pacote e instalá-la; só uma versão fica instalada por vez.
| Versão | Base ESP-IDF | Chips compatíveis | Quando escolher |
|---|---|---|---|
| 1.0.6 | 3.3 | Só ESP32 | Só para recompilar um projeto muito antigo do jeito que está |
| 2.0.17 | 4.4 | ESP32, S2, S3, C3 | Bibliotecas ainda não atualizadas para a 3.x e tutoriais mais antigos |
| 3.x (atual) | 5.x | ESP32, S2, S3, C3, C6, H2 e mais recentes | O padrão para projetos novos e chips novos |
Se você quer que o seu código compile nas duas versões, use a macro de versão. O exemplo abaixo faz o LED da placa acender e apagar suavemente; se ESP_ARDUINO_VERSION_MAJOR for 3 ou mais, ele compila as funções novas de PWM; caso contrário, as antigas. O mesmo truque vale para código de timers e de pinos de toque.
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}Como testar a instalação
Não suponha que está tudo funcionando só porque a instalação terminou. Carregue o sketch abaixo e abra o Monitor Serial em 115200 baud; você vai ver a versão do core instalado, a versão do ESP-IDF, o modelo do chip e o tamanho da flash, e o LED da placa vai piscar. Se aparecerem erros na compilação, o problema ainda é a instalação; se o carregamento terminar com “Failed to connect”, o problema passou a ser a placa, o cabo ou o 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}Ainda não instala? Lista final de verificação
- A data e a hora estão certas? Um relógio errado invalida os certificados das conexões seguras, e todos os downloads falham.
- Seu nome de usuário tem letras acentuadas ou espaços? Algumas ferramentas falham em caminhos com caracteres acentuados ou não latinos; com a configuração directories.data do arduino-cli.yaml, você pode mover a pasta de pacotes para um caminho curto, como C:\Arduino15.
- Limite de caminhos longos do Windows: caminhos com mais de 260 caracteres podem impedir a descompactação do pacote; ativar o suporte a caminhos longos no Windows ou manter os caminhos das pastas curtos ajuda.
- Espaço em disco: os arquivos compactados baixados e os descompactados ficam lado a lado por um tempo durante a instalação, então mantenha pelo menos 5 GB de espaço livre.
- Tente outra ferramenta: se a IDE falhar, tente o Arduino CLI; se ele também falhar, tente o PlatformIO, que baixa os pacotes dos próprios servidores.
- Teste seu código enquanto espera: até a instalação ser resolvida, você pode rodar o circuito e o código no navegador com o simulador Wokwi.
Com o pacote de placas ESP32 instalado corretamente, partir para projetos com Wi-Fi, Bluetooth e sensores é questão de minutos. Se o ESP32 é novidade para você, comece por O que é o ESP32?; depois, no app BlueGrays, você pode fazer passo a passo os projetos de LED com ESP32, de LED da placa e de conexão Wi-Fi, com esquemas do circuito e código pronto para usar.
Perguntas frequentes
Por que o pacote de placas ESP32 não instala?
As causas mais comuns são uma URL do Gerenciador de Placas errada ou desatualizada, uma conexão lenta que estoura o tempo limite, um antivírus travando arquivos e downloads antigos que ficaram pela metade. Confira primeiro se a URL é https://espressif.github.io/arduino-esp32/package_esp32_index.json e depois aplique a solução que corresponde à mensagem de erro do painel Saída.
Qual é a URL correta do ESP32 para o Gerenciador de Placas?
Para a versão estável atual, use https://espressif.github.io/arduino-esp32/package_esp32_index.json. O endereço antigo, dl.espressif.com, só lista versões muito velhas; se ele ainda estiver na sua lista, remova-o, porque duas URLs do ESP32 ao mesmo tempo podem causar problemas.
Como resolver o “Error downloading” na Arduino IDE?
Primeiro tente abrir a URL do pacote em um navegador; se ela não carregar, o problema é a sua rede, o proxy ou o firewall. Se carregar, apague os arquivos parciais da pasta staging, confira o relógio do computador e recomece a instalação por uma conexão cabeada ou pelo hotspot do celular.
Devo instalar o core 2.x ou 3.x do ESP32?
Escolha a 3.x para projetos novos e chips mais recentes, como o ESP32-C6. Se uma biblioteca ou um tutorial de que você depende foi escrito para a 2.x e não compila na 3.x, instale a 2.0.17, a última versão da série 2.x. Você pode trocar de versão quando quiser pela lista suspensa do Gerenciador de Placas.
Dá para instalar o pacote ESP32 sem internet?
Sim. Instale o pacote em um computador com internet e com o mesmo sistema operacional, depois copie a pasta packages/esp32 e o arquivo package_esp32_index.json da pasta Arduino15 dele para o mesmo lugar no computador de destino. Quando você abrir a IDE, o pacote vai aparecer como instalado.
Quanto espaço em disco o pacote ESP32 ocupa?
Depende da versão; as versões 3.x atuais ocupam vários gigabytes com as toolchains e as bibliotecas. Os arquivos compactados e os descompactados coexistem durante a instalação, então manter pelo menos 5 GB de espaço livre é uma margem segura.
Projetos para montar depois desta leitura
Ver todos os projetos
LED integrado do ESP32 piscando
Faça o LED azul integrado do ESP32 DevKit V1 piscar. Nenhum componente externo é necessário! O primeiro projeto para experimentar ao comprar um ESP32. GPIO 2 está conectado ao LED integrado.

LED piscando com ESP32
Ensina o uso básico de uma saída GPIO no ESP32. Fazemos um LED piscar ligando e desligando um pino digital. É a versão para ESP32 do clássico projeto blink do Arduino UNO: os comandos básicos de blink no ambiente Arduino são os mesmos, mas a disposição dos pinos e os níveis de 3,3 V dos GPIOs do ESP32 diferem dos do Arduino UNO.

Controle de LED com botão no ESP32 (momentâneo)
O LED acende enquanto o botão está pressionado e apaga ao soltá-lo. Mostra como usar o pino de entrada digital e o resistor pull-up interno do ESP32. O modo INPUT_PULLUP dispensa um resistor externo.

Semáforo com ESP32
Simulação de um semáforo real com 3 LEDs: vermelho, amarelo e verde. Os tempos se aproximam da lógica real: vermelho longo, amarelo curto e verde longo. Um exemplo clássico de controle sequencial de GPIOs.

Leitura da intensidade da luz com módulo LDR e ESP32
Acompanhe em tempo real no Monitor Serial o valor bruto do ADC do módulo LDR e a porcentagem relativa de luz calculada a partir de referências de escuridão e claridade. Essa porcentagem não é uma medida em lux. O projeto ensina a lógica de calibração do módulo. É ideal fazê-lo antes do projeto 10, pois ajuda a determinar o valor do limiar.

Variação gradual do brilho do LED com PWM no ESP32
Varie suavemente o brilho do LED de 0 ao máximo e do máximo a 0. Controlamos o PWM com analogWrite(), como no Arduino. A mesma sintaxe funciona sem problemas com ESP32 Arduino Core 3.0+. Basta definir o pino e usar pinMode e analogWrite.

Conexão Wi-Fi STA com ESP32 e display LCD
Neste projeto, conectamos o ESP32 à rede Wi-Fi de casa no modo estação (STA), de forma segura e tolerante a falhas. Guardamos o SSID e a senha em um arquivo secrets.h separado para evitar que sejam expostos no Git, configuramos um mecanismo de reconexão automática e exibimos o nível de sinal RSSI e o endereço IP em um display LCD I2C. O LED integrado funciona como indicador de status. É um gerenciador de conexão pronto para uso em produção.

Servidor web assíncrono com ESP32 (IP no LCD)
Neste projeto, transformamos o ESP32 em um servidor web assíncrono que você pode controlar pelo celular ou computador na mesma rede Wi-Fi. Com a biblioteca ESPAsyncWebServer, o servidor processa várias requisições ao mesmo tempo (ao contrário do WebServer.h tradicional, que bloqueia a execução ao processar uma requisição). Você poderá abrir o endereço IP do ESP32 no navegador e clicar nos botões ON/OFF (as rotas /on e /off) para ligar e desligar o LED conectado ao GPIO 5.
Mais artigos
App BlueGrays
Monte este circuito passo a passo pelo celular
Esquema do circuito, código e lista de componentes em uma só tela. Mais de 500 projetos com Arduino, ESP32 e Pico prontos para montar.
Escaneie com seu celular
Aponte a câmera para o código para abrir a loja de aplicativos do seu celular.
ou abrir a loja

