How to Install STM32CubeIDE: Complete Guide from Download to First Project

Working with microcontrollers STM32 starts with the correct installation of development tools. STM32CubeIDE - official Wednesday from STMicroelectronics, which combines a code editor, compiler, debugger and initialization code generator. Without it, it is difficult to imagine effective development for families STM32F1, STM32H7 or STM32L4. But even experienced engineers sometimes encounter installation problems, from Java incompatibility to licensing errors.

This article will help you avoid common mistakes. We will analyze not only the basic installation, but also the nuances for different operating systems, checking the integrity of files, as well as the first steps after launch. Particular attention is paid solving the problem with "invisible" debugger ports, which occurs in 30% of users when they first connect the debug board. If you have previously worked with Keil or IAR, the comparison table at the end of the section will help you adapt faster.

System requirements and preparation for installation

Before downloading STM32CubeIDE, check if your computer meets the minimum requirements. Officially supported:

• 🖥️ Windows: 7/8.1/10/11 (64-bit), 4 GB RAM, 5 GB free disk space
• 🐧 Linux: Ubuntu 18.04+/Debian 9+, Fedora 28+, openSUSE 15+ (64-bit only)
• 🍎 macOS: 10.14 Mojave and later (with Rosetta 2 support for Apple Silicon)

Critical: STM32CubeIDE requires Java 11 or later. If you have an older version installed (for example, Java 8), the environment will either not start or will work with errors. You can check the version with the command:

java -version

For Windows, you will additionally need administrator rights during installation - the program registers drivers for ST-Link and virtual COM ports. On Linux you may need to add the user to groups dialout And plugdev:

sudo usermod -a -G dialout,$USER
sudo usermod -a -G plugdev,$USER

Download STM32CubeIDE: official and alternative sources

The official distribution is always available on the website STMicroelectronics on the way www.st.com → Development Tools → STM32CubeIDE. However, there are nuances:

1. Version from ST website - the most stable, but requires registration (free). After logging in, you will have access to the archive with the latest updates.
2. Mirrors (for example, on SourceForge) - convenient for users with slow Internet, but there is a risk of running into an outdated or modified assembly.
3. Package Manager (for Linux): Ubuntu/Debian repositories often contain outdated versions. It's better to download .tar.gz from the official website.

The size of the distribution is about 1.2 GB for Windows and 1.5 GB for Linux/macOS. The archive already includes:

• 🛠️ Compiler GCC ARM Embedded (version 10.3-2021.10)
• 🔌 Drivers for ST-Link, J-Link and other debuggers
• 📚 Examples of projects for popular boards (Nucleo, Discovery, Eval)

Step-by-step installation on Windows

The installation process on Windows is as automated as possible, but there are pitfalls. Follow the instructions:

1. Unpack the downloaded archive (for example, en.stm32cubeide_1.13.0_11591_20230721_0836_x64.exe).
2. Run the installer as an administrator. If a SmartScreen warning appears, click “More details” → “Run anyway”.
3. At the component selection stage, leave the checkboxes on:
   • 🔧 STM32CubeIDE (main environment)
   • 🖥️ STM32CubeMX (graphical configurator)
   • 🔌 ST-Link drivers (drivers for debuggers)

Specify the installation path. The default is C:\ST\STM32CubeIDE. Do not use paths with Cyrillic or spaces - this will lead to compilation errors.

Wait for it to complete (may take 10-15 minutes). At the last stage, the installer will offer to start the environment - uncheck the box, since you first need to restart the PC.

After the reboot, check the drivers: connect the debug board (for example, STM32F407G-DISC1) and open Device Manager. The following should appear:

• 🔌 STMicroelectronics ST-Link (in the "USB Controllers" section)
• 📡 STMicroelectronics Virtual COM Port (in the "Ports" section)

⚠️ Attention: If the ports are not detected, try connecting the board to another USB port (preferably USB 2.0). Some laptops block uncertified USB devices through the BIOS - check your security settings.

Installation on Linux: resolving dependencies and permissions

On Linux the process is more complex due to dependencies and permissions. Let's look at the installation using an example Ubuntu 22.04 LTS:

1. Unpack the archive stm32cubeide_1.13.0_11591_20230721_0836_linux.x86_64.tar.gz to home directory:

   tar -xvzf stm32cubeide_*.tar.gz -C ~/
   cd ~/stm32cubeide_*/

2. Run the installer:

   sudo ./SetupSTM32CubeIDE-linux_x86_64

3. If you receive an error about missing libraries, install them:

   sudo apt install libgtk-3-0 libcanberra-gtk-module libnss3

4. After installation, add rules for udevso that you don't need to run the IDE as root:

   sudo cp ~/ST/STM32CubeIDE_1.13.0/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.10.3-2021.10.linux64_1.0.0.202307210836/tools/udev/* /etc/udev/rules.d/
   sudo udevadm control --reload-rules
   sudo udevadm trigger

To launch STM32CubeIDE, create a shortcut on your desktop with the following content:

[Desktop Entry]
Name=STM32CubeIDE
Exec=/opt/st/stm32cubeide_1.13.0/stm32cubeide
Icon=/opt/st/stm32cubeide_1.13.0/icon.xpm
Terminal=false
Type=Application
Categories=Development;IDE;

⚠️ Attention: On distributions with Wayland (for example, Fedora 36+) there may be problems with displaying the STM32CubeMX interface. The solution is to launch via Xorg or setting an environment variable export GDK_BACKEND=x11 before starting the IDE.

First launch and setup of the working environment

When you launch it for the first time, STM32CubeIDE will offer:

1. Select the working directory (workspace). We recommend creating a separate folder, for example, ~/STM32Projects.
2. Import example projects (optional). For beginners it is useful to choose STM32CubeF4 → Examples → GPIO → GPIO_IOToggle.
3. Activate the license. Although STM32CubeIDE is free, you are required to accept the agreement SLA0048 (opens in browser).

After loading the interface, check the key settings:

• 🔧 Window → Preferences → C/C++ → Build → Settings: make sure compiler is selected STM32CubeIDE (not system GCC).
• 🔌 Window → Preferences → STM32Cube → Firmware Updater: Enable automatic check for updates for STM32CubeMX.
• 📡 Run → Debug Configurations: check that the list of available debuggers is ST-Link (OpenOCD).

To speed things up, disable unnecessary plugins:

Window → Preferences → General → Startup and Shutdown

Parameter	Recommended value	Explanation
Max parallel jobs	4	Optimal for 4-8 core processor
Console buffer size	10000	Prevents logs from being trimmed during long compilations
Auto-save interval	5 minutes	Saves the project on failure
Show heap status	Included	Helps track memory leaks in debug sessions

Solving common installation errors

Even if you follow the instructions exactly, problems may arise. Let's look at typical cases and their solutions:

1. Error "Java not found" or "Unsupported Java version"

STM32CubeIDE comes with a built-in JVM, but sometimes tries to use the system one. Solution:

• Open the file STM32CubeIDE.ini in the installation folder.
• Add the lines:

  -vm
  C:/ST/STM32CubeIDE/plugins/org.eclipse.justj.openjdk.hotspot.jre.full.win32.x86_64_17.0.2.v20220115-0940/jre/bin/javaw.exe

  (path may vary depending on version)

2. The debugger does not see the board (error "No ST-Link detected")

The problem occurs more often on Windows 10/11 due to a driver conflict:

• Open Device Manager and remove all devices named ST-Link.
• Connect the board, wait for the drivers to install (you should see STMicroelectronics ST-Link in the "USB Controllers" section).
• If this does not help, install the driver manually from the folder C:\ST\STM32CubeIDE\drivers.

3. License error "License agreement not accepted"

Sometimes the agreement is not saved after the first launch. Solution:

• Delete the file .metadata/.plugins/org.eclipse.core.runtime/.settings/org.eclipse.ui.prefs in the working directory.
• Restart the IDE and accept the agreement again.

What to do if STM32CubeIDE does not see the COM port?

1. Check the physical connection of the board (the power indicator should be on).

2. In Device Manager, update the driver for the "Unidentified device" (specify the folder C:\ST\STM32CubeIDE\drivers).

3. Try a different USB cable (some cables are for charging only).

4. On Linux, check permissions: ls -l /dev/ttyACM* — there must be read/write access for your user.

Comparison of STM32CubeIDE with other development environments

STM32CubeIDE is not the only tool for working with STM32. Let's compare it with popular alternatives:

Parameter	STM32CubeIDE	Keil MDK	IAR Embedded Workbench	PlatformIO + VSCode
Cost	Free	From $3500 (code limit 32KB in free version)	From $3000 (limit 32KB)	Free (with open tools)
Integration with STM32CubeMX	Full (built-in plugin)	Partial (project export)	Partial	Through code generation
Debugger	ST-Link, J-Link (OpenOCD)	ULINK, J-Link, ST-Link	J-Link, ST-Link, I-Jet	OpenOCD, J-Link, ST-Link
OS support	Windows, Linux, macOS	Windows only	Windows, Linux (limited)	Cross-platform
Code generation	Automatic via CubeMX	Manual or via STM32CubeMX	Manual or via CubeMX	Via CubeMX + scripts

STM32CubeIDE wins in terms of price/functionality, especially for educational projects and prototyping. However, for commercial products with strict code optimization requirements, many prefer Keil or IAR due to more mature compilers.

PlatformIO is an interesting alternative for those who are used to VSCode, but requires additional configuration to fully work with STM32CubeMX.

FAQ: Frequently asked questions about installing STM32CubeIDE

Is it possible to install STM32CubeIDE on 32-bit Windows?

No, starting from version 1.8.0 only 64-bit systems are supported. The latest 32-bit version is 1.7.0, but it is outdated and does not support newer microcontrollers (e.g. STM32H5 or STM32U5). We recommend updating your OS or using a virtual machine with 64-bit Windows.

How to transfer a project from Keil to STM32CubeIDE?

There is no direct import, but you can:

1. Export project from Keil in format .uvprojx.
2. Create a new project in STM32CubeIDE via File → New → STM32 Project.
3. Copy source files (.c, .h) from the Keil folder to a new project.
4. Reconfigure compiler parameters manually (optimization options, include paths).

For complex projects, it is easier to generate a workpiece via STM32CubeMX and transfer only the business logic.

STM32CubeIDE slows down on a large project. How to speed up work?

Try the following:

• Disable automatic index building (Window → Preferences → C/C++ → Indexer → Enable indexer: Off).
• Increase heap memory for IDE: in file STM32CubeIDE.ini add the line -Xmx2048m.
• Close unnecessary prospects (Window → Perspective → Close All).
• Use an SSD drive for the working directory.

If the project contains many files, split it into several subprojects with shared libraries.

Is it possible to use STM32CubeIDE without internet?

Yes, but with reservations:

• The IDE itself works offline after installation.
• To update STM32CubeMX and microcontroller packages will require the Internet (you can download packages in advance via STM32CubeMX → Help → Manage embedded software packages).
• When you first start, you need to accept the license agreement (one-time Internet access is required).

For completely offline work, download offline versions of packages from the ST website and install them via Help → Install New Software → Add → Archive.

How to remove STM32CubeIDE completely?

For complete removal:

1. Delete the installation folder (default C:\ST\STM32CubeIDE or /opt/st/stm32cubeide_*).
2. Remove working directories (usually in ~/STM32Cube/workspace_*).
3. On Windows, delete registry entries:

   HKEY_CURRENT_USER\Software\STMicroelectronics\STM32CubeIDE
   HKEY_LOCAL_MACHINE\SOFTWARE\STMicroelectronics\STM32CubeIDE

4. On Linux, remove udev rules:

   sudo rm /etc/udev/rules.d/49-stlink*.rules
   sudo rm /etc/udev/rules.d/70-persistent-stlink.rules

After uninstallation, it is recommended to restart your computer.