esptool: Como Gravar ESP32 e ESP8266 Passo a Passo (Guia 2026)

O esptool é o programa oficial da Espressif que grava, lê e apaga a memória flash do ESP32 e do ESP8266 pela porta serial. Ele trabalha escondido dentro do Arduino IDE e do PlatformIO — e é o que você usa direto para regravar um .bin, fazer backup da flash ou ressuscitar uma placa que não responde.

Este guia mostra o download oficial, a instalação em cada sistema, os comandos que o técnico realmente usa e os cinco erros mais comuns, com a fonte de cada correção. Última verificação: 17 de setembro de 2026.

esptool.py ou esptool? O nome mudou na versão 5

Quase todo tutorial na internet ainda escreve esptool.py write_flash. Desde a versão 5, o guia oficial de migração da Espressif diz que o jeito preferido é chamar esptool, sem o “.py”, e que todos os comandos e opções trocaram o sublinhado pelo hífen: write_flash virou write-flash, --flash_mode virou --flash-mode, default_reset virou default-reset.

Os nomes antigos ainda funcionam, mas com aviso. Conferimos na versão 5.4.0: rodar esptool.py imprime “WARNING: DEPRECATED: ‘esptool.py’ is deprecated. Please use ‘esptool’ instead”, e write_flash gera “Command ‘write_flash’ is deprecated. Use ‘write-flash’ instead”. Eles saem na próxima versão principal; neste guia usamos a forma nova.

Download oficial: versão atual e para qual sistema

A versão estável mais recente é a esptool 5.4.0, publicada em 2 de setembro de 2026. Há dois caminhos oficiais, e os links abaixo apontam só para a Espressif — não hospedamos nenhum arquivo:

Os executáveis prontos ficam na página de releases do GitHub da Espressif. O SHA-256 do pacote de Windows, publicado junto do release, é b7f6b9dd301a210b31f4829118c909c84aae23107f9ca1fdc14ccf4d7384be2e — confira com certutil -hashfile esptool-v5.4.0-windows-amd64.zip SHA256 antes de extrair.

Qual escolher? O manual de instalação lista as limitações do executável pronto: é bem maior, abre mais devagar e “pode ser apontado como malware pelo antivírus”. O próprio release traz a análise de cada arquivo no VirusTotal e diz que esses alertas são provavelmente falsos positivos. Se você já tem Python, o pip é o caminho mais limpo; se não quer instalar nada, o executável resolve.

Instalação passo a passo

Windows 10 e 11

1. Sem Python: baixe o .zip de Windows, confira o SHA-256, extraia numa pasta curta (ex.: C:\esptool) e abra o Prompt de Comando nela. Rode esptool version.
2. Com Python 3.10 ou mais novo: rode python -m pip install esptool e depois python -m esptool version.
3. Antes de conectar a placa, instale o driver do conversor USB-serial dela — CH340, CP2102 ou CH9102. Sem ele, não existe porta COM para o esptool usar.

Linux

O manual recomenda um ambiente virtual para não bagunçar o Python do sistema: python3 -m venv esptoolenv, depois source esptoolenv/bin/activate e pip install esptool. Para ter acesso à porta sem sudo, adicione seu usuário ao grupo dialout (ou uucp, conforme a distribuição) e faça logout. Aviso do guia de migração: o executável pronto de Linux da versão 5 exige glibc 2.35 (Ubuntu 22.04 ou mais novo).

macOS

Com Python instalado, o mesmo pip install esptool. Com o executável, extraia o .tar.gz da arquitetura certa (arm64 para M1/M2/M3/M4). A porta aparece como /dev/cu.usbserial-… ou /dev/cu.wchusbserial….

Os comandos que o técnico usa

Troque COM4 pela sua porta (no Linux, /dev/ttyUSB0 ou /dev/ttyACM0). O --chip é opcional: o esptool detecta o chip ao conectar.

• Identificar chip e flash: esptool -p COM4 flash-id — mostra o modelo, a revisão, o MAC e o tamanho da flash. É o primeiro teste de qualquer placa.
• Backup antes de mexer: esptool -p COM4 -b 460800 read-flash 0 ALL backup.bin — o ALL detecta o tamanho da flash sozinho.
• Apagar tudo: esptool -p COM4 erase-flash.
• Gravar um arquivo único (o “merged” ou “factory” que muitos projetos distribuem): esptool -p COM4 write-flash 0x0 firmware-completo.bin.
• Gravar arquivos separados: esptool -p COM4 -b 460800 write-flash 0x1000 bootloader.bin 0x8000 partitions.bin 0x10000 app.bin.

Um cuidado que derruba muita gente: o endereço do bootloader muda conforme o chip. Pela documentação oficial, é 0x1000 no ESP32 e no ESP32-S2, 0x0 no ESP32-C3, S3, C6 e ESP8266, e 0x2000 no ESP32-C5 e P4. A tabela de partições costuma ir em 0x8000 e a aplicação em 0x10000. Na dúvida, não chute: no Arduino IDE, ative nas Preferências a saída detalhada durante o carregamento (upload), e o comando completo com os endereços certos aparece na tela.

Outra novidade da versão 5: a verificação depois da gravação é automática. A opção --verify foi descontinuada e a conferência do hash acontece sozinha sempre que possível — a linha “Hash of data verified” confirma.

Como colocar a placa em modo de gravação

O esptool só conversa com o chip quando ele reinicia em modo download. Nas placas de desenvolvimento comuns isso é automático: o conversor USB-serial usa as linhas DTR e RTS para puxar o GPIO0 para baixo durante o reset. Quando o automático falha, a documentação manda fazer à mão: segure o botão BOOT e aperte e solte o EN (ou segure o BOOT enquanto o esptool mostra “Connecting…” e só solte quando conectar).

No ESP8266 o pino de modo também é o GPIO0, e a documentação acrescenta que o GPIO2 não pode estar ligado direto ao VCC, porque o bootloader usa esse pino como saída.

Os cinco problemas mais comuns (e a correção)

1. “‘esptool.py’ não é reconhecido como um comando interno”. Foi o caso da issue #777 do repositório oficial (Windows 11, setembro de 2022): o pip dizia que o esptool estava instalado, mas o comando não existia. O engenheiro da Espressif respondeu que é problema de PATH — a pasta de scripts do Python não está no caminho do sistema. A saída mais simples, confirmada por outro usuário no mesmo tópico e pela documentação (que avisa que no Python da Microsoft Store “provavelmente só python -m esptool vai funcionar”), é rodar python -m esptool.

2. “Wrong boot mode detected (0x13)! The chip needs to be in download mode”. A comunicação existe, mas o reset automático não levou o chip ao modo de gravação. Na issue #1016 (outubro de 2024, NodeMCU ESP-32S no Windows 11), o usuário só conseguia gravar segurando o botão IO0, e a Espressif explicou que a combinação de driver, sistema e controlador USB estava estragando a sequência de reset. Correção: modo manual (BOOT + EN) ou, para não depender do botão, uma sequência de reset personalizada no arquivo de configuração do esptool. A documentação sugere ainda um capacitor de 1 µF ou mais entre EN e GND em placas de terceiros que não o têm — sem ele o reset automático fica instável, “especialmente no Windows”. Na issue #949 (janeiro de 2024), o culpado era um circuito externo ligado aos pinos do ESP32 — vale desconectar tudo antes de gravar.

3. “Failed to connect: No serial data received”. Nem um byte voltou. A documentação diz que isso “normalmente indica problema de hardware”: RX/TX desligados, placa sem entrar em modo download, porta errada ou outro programa (um monitor serial esquecido aberto) segurando a porta. Confira a porta e a alimentação de 3,3 V com o multímetro e tente com -b 115200 ou até -b 9600.

4. “Invalid head of packet (0x00): Possible serial noise or corruption”. Na issue #1106 (julho de 2025), uma placa ESP32 com CP2102 falhava a 921.600 baud na versão 5.0.1 enquanto uma com CH340 gravava normal; o desenvolvedor da Espressif pediu para baixar a velocidade e atualizar o driver do CP2102,. A lista oficial acrescenta cabo USB ruim, protoboard em curto com pinos da flash e queda de tensão. Correção prática: baixe o baud, troque o cabo, atualize o esptool e o driver.

5. Gravou, mas a placa não liga o programa. A documentação aponta dois suspeitos. Primeiro, o modo da flash: alguns módulos só aceitam dio — grave com --flash-mode dio. Segundo, alimentação: o ESP pede até 70 mA contínuos e picos de 200 a 300 mA, e o manual é direto: “a saída de 3,3 V de chips FTDI FT232R e de placas Arduino não fornece corrente suficiente”. Uma fonte de bancada com regulador de 3,3 V tira a dúvida.

A parte que ninguém conta

O Arduino IDE e o PlatformIO usam uma cópia própria do esptool, que pode estar várias versões atrás. Na issue #1016, o Arduino usava a 4.6 enquanto a atual era a 4.8.1 — atualizar o esptool do sistema não muda nada dentro do IDE. Se um erro some quando você grava pela linha de comando e volta pelo IDE, é essa diferença de versão.

E para quem só quer gravar sem digitar comando, existe o Flash Download Tool, a ferramenta gráfica da Espressif para Windows. Ela resolve o dia a dia; o esptool é o que funciona em qualquer sistema, cabe num script e dá a mensagem de erro detalhada quando algo dá errado. Registro de honestidade: não temos relação comercial com a Espressif.

Perguntas frequentes

O esptool ainda grava o ESP8266? Sim. Conferimos na versão 5.4.0: esp8266 continua na lista de chips da opção --chip, ao lado de ESP32, S2, S3, C2, C3, C5, C6, H2 e P4.

Meus scripts antigos com esptool.py write_flash param de funcionar? Por enquanto não: na versão 5 eles rodam com aviso. A Espressif avisa que os nomes antigos saem na próxima versão principal, então atualize os scripts trocando sublinhado por hífen.

Dá para copiar o firmware de uma placa boa para outra igual? Dá para ler com read-flash 0 ALL e gravar com write-flash 0x0, desde que a placa não tenha criptografia da flash ou Secure Boot ativos — nesses casos a leitura é bloqueada ou volta cifrada.

Conclusão

Três regras resolvem a maioria dos casos: use esptool com hífen (ou python -m esptool quando o comando “não existe”); erro de conexão se resolve com BOOT + EN e baud mais baixo; e endereço de gravação depende do chip — copie do log do IDE em vez de adivinhar.

No próximo guia da série vamos ao Arduino IDE 2: por que a porta COM não aparece e como corrigir drivers e placas.

Se você grava firmware para consertar equipamento e quer entender o que existe em volta do chip numa placa desconhecida, o Mapa da Placa é o nosso material de leitura de placa — vale conhecer.