O STM32CubeIDE é o ambiente gratuito da ST para escrever, gravar e depurar firmware nos microcontroladores STM32 — e, desde a versão 2.0, ele deixou de ser aquilo que praticamente todo tutorial em português ainda mostra. Aqui estão o link oficial, a versão corrente conferida por nós em 2 de outubro de 2026, a instalação nos três sistemas, a mudança que faz o .ioc abrir como bloco de notas, e os cinco problemas mais comuns.
O que é o STM32CubeIDE — e o que vem dentro dele
É um Eclipse com compilador de Arm, gravador e depurador embutidos, distribuído de graça pela fabricante dos chips: você escreve C/C++, compila, e ele grava o STM32 pelo ST-LINK e para o programa na linha que você mandar.
A versão corrente é a 2.2.0. Conferimos na nota de versão oficial — a RN0114, revisão 39, de 22 de junho de 2026 —, que também lista o que o instalador coloca no seu disco:
- Eclipse 2025-12 com CDT 12.3.0, GCC Arm Embedded 14.3, GDB e o STARM-Clang 21.1.1 da própria ST;
- STM32CubeProgrammer 2.23.0 em linha de comando, para gravar;
- ST-LINK GDB server 7.14.0 (atende ST-LINK/V2 e STLINK-V3), servidor J-Link da SEGGER e OpenOCD;
- CMake, Ninja e um Java Temurin 21 próprio — você não precisa instalar Java à parte.
É gratuito, sob a licença SLA0048 da ST: não existe versão paga nem limite de linhas de código.
Onde baixar: o link oficial
Um endereço, e só ele: st.com/en/development-tools/stm32cubeide.html. O botão fica na seção Get Software, no fim da página, e a ST pede o aceite da licença antes de liberar o arquivo. Fuja de blog com botão verde: é uma ferramenta que vai gravar firmware na sua placa.
| Sistema | Versões oficialmente suportadas (v2.2.0) | Arquivo |
|---|---|---|
| Windows | 10 e 11, somente 64 bits | st-stm32cubeide_VERSÃO_x86_64.exe |
| Linux | Ubuntu LTS 26.04 e Fedora 44 | ..._amd64.deb_bundle.sh, ..._rpm_bundle.sh ou .sh genérico |
| macOS | 15 (Sequoia) e 26 (Tahoe) | ..._x86_64.dmg — Apple Silicon nativo desde a 2.1.0 |
Requisitos, também da nota oficial: 4 GB de RAM recomendados e 6 GB de disco livre (15 GB para quem for mexer com os microprocessadores STM32MP).
Repare na linha do Linux, porque ela mudou e ninguém avisou: na nota da última versão 1.x (revisão 35, junho de 2025), a lista dizia Ubuntu LTS 22.04 e 24.04, Fedora 41. Hoje diz apenas Ubuntu 26.04 e Fedora 44. Quem está no 24.04 LTS saiu da lista de sistemas testados: instala e funciona na prática, mas se der problema você está fora do que a ST garante.
A mudança que quebra todo tutorial: o CubeMX saiu de dentro
Esta é a parte que ninguém conta, e é a razão deste guia. Até a 1.19 o fluxo era um só: File → New STM32 Project, escolher o chip, e abria ali dentro o configurador gráfico — pinos, clock, periféricos — que gerava o código HAL. Esse configurador é o STM32CubeMX, e ele não está mais dentro do STM32CubeIDE desde a versão 2.0.0.
Não é boato de fórum: está no histórico do manual oficial, o UM2609. A revisão 16, de 5 de novembro de 2025, abre com a frase “documento atualizado para o STM32CubeIDE v2.0.0 sem integração com o STM32CubeMX” e lista duas seções removidas:
Comparamos aqui as duas revisões do mesmo manual, a 15 (junho de 2025, era 1.x) e a 18 (junho de 2026, era 2.x). A contagem fala sozinha: as menções a “STM32CubeMX” caíram de 21 para 10, as da “Device Configuration Tool” de 6 para 1, e a extensão .ioc, que aparecia quatro vezes, não aparece nenhuma vez na revisão nova.
Três consequências práticas, todas conferidas no texto do manual:
- O menu mudou de nome. Era [File] → [New STM32 Project]; agora é [File] → [STM32 Project Create/Import].
- O assistente cria um projeto vazio. O manual de 2026 é literal: escolha o alvo no MCU/MPU Selector ou no Board Selector “para criar um projeto vazio”. Sumiu a opção de tipo STM32Cube, que era quem trazia o HAL e abria o configurador.
- O login acabou. Aquele cadastro que a IDE pedia para baixar pacote de firmware não existe mais.
Instalação, passo a passo
Windows
Rode o .exe com conta de administrador — o guia de instalação da ST (UM2563) é explícito nisso, porque os drivers do ST-LINK são instalados junto. O Windows vai perguntar se permite o aplicativo fazer alterações, com a assinatura “Verified publisher: STMicroelectronics Software AB”; se o nome do editor for outro, pare tudo: o arquivo não é da ST.
Aceite a licença e, na pasta de destino, escolha um caminho curto (C:STCubeIDE) — recomendação do próprio manual, para não esbarrar depois no limite de caminho do Windows. Na tela seguinte, marque os servidores GDB: o do ST-LINK sempre; o da SEGGER só se tiver um J-Link na gaveta.
Linux
O pacote vem como um instalador de shell. Abra o terminal na pasta do arquivo e rode com root:
sudo sh ./st-stm32cubeide_VERSÃO_amd64.deb_bundle.sh
Troque por rpm_bundle.sh em Fedora, ou use o .sh genérico. O pacote instala junto as regras de udev do ST-LINK e do J-Link — é isso que faz o gravador aparecer para o seu usuário sem sudo. Se a IDE reclamar de missing libncurses5.so, a própria ST manda instalar a biblioteca de compatibilidade (ncurses-compat-libs, no Fedora).
macOS
Abra o .dmg com conta de administrador. No primeiro disparo o Gatekeeper pede permissão, porque o programa não veio da App Store — é esperado. Em Mac com chip da Apple, desde a 2.1.0 existe versão ARM64 nativa, sem a muleta do Rosetta.
O primeiro projeto, do jeito que funciona hoje
Para piscar um LED com o HAL — o “olá, mundo” do STM32 —, o caminho em 2026 tem um passo a mais do que o dos tutoriais antigos:
- Instale também o STM32CubeMX, de graça, em st.com/en/development-tools/stm32cubemx.html. Sem ele você não tem configurador gráfico.
- No CubeMX, escolha a placa na aba Board Selector (uma Nucleo, por exemplo) ou o chip no MCU Selector, e configure o pino do LED como saída.
- Em Project Manager, dê nome ao projeto, escolha STM32CubeIDE no campo de IDE e gere o código.
- Abra o projeto gerado no STM32CubeIDE, por [File] → [STM32 Project Create/Import].
- No
main.c, dentro dowhile (1), duas linhas:HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5);eHAL_Delay(500);— ajustando porta e pino aos da sua placa. - Martelo para compilar, ST-LINK no USB, Run. Quem grava é o STM32CubeProgrammer que já veio dentro.
Quer ficar só no CubeIDE? Dá: o assistente cria o projeto vazio, com o código de inicialização e o main.c, e você escreve direto nos registradores. Mais trabalho, mais aprendizado.
Os cinco problemas mais comuns — e a correção
1. O arquivo .ioc abre como texto. É o problema número um de quem atualizou — relatado na comunidade da ST em 30 de novembro de 2025, por quem pulou da 1.9 para a 2.0.0. A resposta do moderador técnico da ST: o .ioc precisa ser associado, no sistema, ao aplicativo MicroXplorer for STM32Cube, nome com que o CubeMX autônomo se registra.
2. O instalador diz que já existe uma versão instalada. Acontece quando uma instalação anterior foi removida pela metade. O guia oficial manda abrir o regedit e apagar a chave HKEY_LOCAL_MACHINESOFTWAREWOW6432NodeSTMicroelectronicsSTM32CubeIDE; depois disso ele volta a rodar.
3. “ST-LINK firmware upgrade required” ou erro na sequência final de carga. Clássico do gravador: atualize o firmware do ST-LINK pela ferramenta que vem junto, antes de qualquer outra coisa. Se a atualização também falhar, suspeite do cabo — há relatos na comunidade da ST de atualização que só passou depois de trocar o cabo USB. Clone barato às vezes recusa a atualização; aí a saída é baixar a frequência do SWD. Nosso guia do ST-Link V2 trata disso em detalhe.
4. No Linux, a placa não aparece. Quase sempre é regra de udev: se você instalou descompactando em vez de rodar o bundle com sudo, os pacotes st-stlink-udev-rules e st-stlink-server ficaram de fora — instale-os à mão.
5. Compila aqui e não compila ali. Caminho longo, com espaço ou com acento, continua sendo veneno no Windows: instale em caminho curto e crie o workspace fora do OneDrive. E, se instalou como administrador, atualize também como administrador — a ST avisa que o mecanismo de atualização exige os mesmos privilégios da instalação.
Para seguir este guia até o LED piscar, duas compras que resolvem a bancada:
Como Associados da Amazon, recebemos por compras qualificadas feitas pelos links acima — você não paga nada a mais por isso, e ajuda o site a continuar gratuito.
Perguntas frequentes
O STM32CubeIDE é pago? Não. É gratuito, sem limite de código. O que custa dinheiro é o hardware.
Preciso mesmo instalar o STM32CubeMX separado? Se quer o configurador gráfico de pinos e clock e o código HAL gerado, sim, da versão 2.0.0 em diante. Se vai escrever tudo na mão, o CubeIDE sozinho basta.
Vale ficar na 1.19 para manter tudo junto? Em projeto antigo, até o fim dele, faz sentido — as versões convivem na mesma máquina. Para começar algo novo, não: a 2.x é a linha que recebe chip novo e correção.
Dá para usar clone de ST-LINK V2? Dá, e é o que a maioria usa. Só conte com a possibilidade de ele travar na atualização de firmware.
Onde está a lista de bugs conhecidos? Essa é a parte chata: a nota de versão não traz nenhum. Ela aponta 51 vezes para um wiki de errata e avisa, em dez pontos, que o acesso exige login — para saber o que está quebrado na sua versão, você precisa de conta na ST.
O resumo que cabe na bancada
Baixe só da página da ST, instale como administrador em caminho curto e marque o servidor GDB do ST-LINK. Se você veio de um tutorial de 2023 e o configurador gráfico não apareceu, não é defeito da sua instalação: o CubeMX saiu de dentro da IDE em novembro de 2025, e agora são dois programas. Em quarenta versões lançadas desde abril de 2019, essa foi a maior mudança de rumo da ferramenta.
No próximo guia a fila segue para a ferramenta que monta o pendrive do técnico: o Raspberry Pi Imager — download oficial, gravação do cartão e o que ele faz melhor que os concorrentes.
Veja também
- ST-Link V2: driver e STM32CubeProgrammer — o gravador que o CubeIDE usa.
- KiCad 10: download e o primeiro esquema — o outro lado, quando a placa ainda não existe.
- esptool.py: gravar ESP32 e ESP8266 — o mesmo trabalho, do lado da Espressif.
Se a sua próxima pergunta for sobre a placa que está na bancada esperando — qual chip ler primeiro e por onde começar a medir —, o Mapa da Placa é o nosso material de leitura de placa; vale conhecer.
