# STM32CubeMX projects

> **TL;DR**
> OS: Windows, Linux, macOS
>
>
>
> Required tools: STM32CubeMX, STM32CubeCLT
>
>
>
> Project format: CMake

CLion integrates with [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) for embedded projects targeting [STM32](https://www.st.com/en/microcontrollers-microprocessors/stm32-32-bit-arm-cortex-mcus.html) boards. Before working with these projects in the IDE, you need to install STM32CubeMX and [STM32CubeCLT](https://www.st.com/en/development-tools/stm32cubeclt.html). Then, you can open an existing STM32CubeMX project or create a new one.

CLion also supports Cube CLI, the bundle manager from ST. It lets you download only the tools you need, such as CMake, the ST-LINK GDB server, or GNU tools, and manage your development bundles in the IDE (see details in the chapter below). To use Cube CLI, make sure that `cube` is installed on your machine.

> **Note:**
> [STM32Mxx Arm Cortex MPUs](https://www.st.com/en/microcontrollers-microprocessors/stm32-arm-cortex-mpus.html) are not supported at the moment. If you need these boards to work with CLion, feel free to share your use case with us in [CPP-42553](https://youtrack.jetbrains.com/issue/CPP-42553/Rework-STM32CubeMX-support).

## Work with STM32CubeMX projects

Procedure: Open a project

* When you launch CLion, click Open on the Welcome screen.

![project dialog](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_open_project.png)

Then, navigate to your project folder, select it, and click Open. CLion then will open your project as a CMake one.

* You can also select the `.ioc` file in the project folder and then click Open as Project. Make sure that the name of the `.ioc` file does not contain spaces, non-latin symbols, or other special characters.

* If CLion is already run, navigate to `File` `| Open` and open the project folder or the `.ioc` file.

Procedure: Create a new project

> **Note:**
> First, ensure that you have both [STM32CubeCLT](https://www.st.com/en/development-tools/stm32cubeclt.html) and [STM32CubeMX](https://www.st.com/en/development-tools/stm32cubemx.html) installed on your system.

1. In CLion, navigate to `File | New | Project` and select STM32CubeMX as your project type:

![new stm32 project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_new_project.png)

You can then follow the steps shown on the New Project screen or the more detailed instructions below.

> **Tip:**
> In steps 2–10, we will only use the STM32CubeMX settings necessary for working with CLion. For more information about the STM32CubeMX capabilities, refer to the [official documentation](https://wiki.stmicroelectronics.cn/stm32mcu/wiki/Introduction_to_STM32CubeMX).

2. Launch STM32CubeMX. In the window that opens, click ACCESS TO MCU SELECTOR. You can also select ACCESS TO BOARD SELECTOR.

![cubemx access to mcu selector](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_access_mcu_board.png)

3. Find your MCU or board in the list, then click Start Project in the upper right corner:

![cubemx start project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_start_project.png)

4. The Pinout & Configuration tab will open. From there, you can change the default settings displayed in Pinout view, configure additional parameters, or install middleware if necessary.

![cubemx pinout view](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_pinout_configuration.png)

5. Click the Project Manager tab.

6. From the Toolchain / IDE dropdown menu, select CMake:

![cubemx cmake toolchain](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_toolchain_cmake.png)

7. In the Project Name field, enter the name of your project:

![cubemx project name](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_project_name.png)

8. In the upper right corner, click Generate Code.

9. Once generation is finished, close the Code Generation window:

![cubemx code generation](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_code_generation.png)

10. Copy the path from the Toolchain Folder Location field using the keyboard shortcut: `^C` on macOS or `Ctrl + C` on Windows/Linux:

![cubemx toolchain location](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_toolchain_location.png)

11. Switch back to the CLion New Project window. Enter the path you copied in the Location field at the top of this dialog, then click Proceed:

![project location](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_proceed.png)

12. Your STM32CubeMX project will be created:

![new project created](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_project_created.png)

> **Note:**
> After creating a new STM32CubeMX project, CLion automatically configures the appropriate [CMake profile](cmake-profile.html) and [debug profile](debug-profiles.html). You can use these default configurations to build, run, or debug your project right away.

Procedure: Build a project

To build your project, click the ![](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.build.build.svg) button on the main toolbar:

![build project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_build.png)

If everything works correctly, you will see `Build finished` in the Messages window:

![build finished](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_build_finished.png)

Procedure: Debug a project

1. Ensure that you have configured the appropriate run/debug configuration and the ST-LINK debug server. If it is a new STM32CubeMX project, you can use the default settings that CLion pre-configures.

2. Set a breakpoint in your source code, then click the ![](https://resources.jetbrains.com/help/img/idea/2026.2/app-client.expui.run.debug.svg) button on the main toolbar:

![debug project](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_start_debugging.png)

If everything works correctly, you will see the message in the debugger `Console` tab: `Debugger connected to ST-LINK`.

3. Once your program has been suspended, you can perform various actions, such as:

* View the [registers and peripherals](peripheral-view.html) defined in `.svd` files. For STM32 MCUs, these files are located in the `STMicroelectronics_CMSIS_SVD` directory within the `STM32CubeCLT` installation directory.

* Use [live watches](live-watches.html) to monitor global variables in real time.

* Debug [disassembled code](disassembly-view.html).

* View [raw memory](memory-view.html) of running processes.

![debugging](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_debug.png)

Procedure: Edit source code

* While editing the files generated by STM32CubeMX, always enclose your code in the `/* USER CODE BEGIN ... */` and `/* USER CODE END ... */` pseudo comments. Here is an example:

```C
               /* Infinite loop */
/* USER CODE BEGIN WHILE */
while (1)
{
  HAL_GPIO_TogglePin(LD3_GPIO_Port, LD3_Pin);
  HAL_Delay(1000);
  /* USER CODE END WHILE */
```

This will protect your code from being overwritten by STM32CubeMX during code regeneration.

* If you add source or header files, place them in the `Src` and `Inc` directories. Also, extract pieces of code into separate `.c` or `.h` files.

## Manage bundles with Cube CLI

Cube CLI distributes development tools as bundles: CMake, compilers, the ST-LINK GDB server, GNU tools, and other components. In a Cube project, the bundles and their versions are locked in the project files so that every environment that builds the project uses the same set of tools.

> **Note:**
> Cube CLI works with the System, MinGW, WSL, and Remote SSH toolchains. With a Docker toolchain, you can use only the bundles that are already installed in the image.

Procedure: Configure Cube CLI

1. Install `cube` as described in the [ST documentation](https://dev.st.com/stm32cube-docs/stm32cubedocs-landing-page/en/index.html).

2. CLion detects the `cube` executable automatically. To check the detected path or set it manually for the current default toolchain, open `Settings | Build, Execution, Deployment | Embedded Development | STM32` and use the Cube CLI Command field.

![Check if CLion detects the cube executable in the settings](https://resources.jetbrains.com/help/img/idea/2026.2/cl_stm32_cube_cli_command.png)

3. Cube CLI extends the environment of your CMake profiles with the bundles locked in the project. This feature is enabled by default. To turn it off, clear the Use STM32 Cube CLI to extend CMake's environment checkbox under STM32 in [advanced settings](advanced-settings.html#advanced-stm32).

Procedure: Convert a project to a Cube project

When your project is not a Cube project yet, `Tools | STM32 Cube CLI` contains two actions: Convert to STM32 Cube Project and Open STM32 Cube CLI Terminal. For the terminal action, refer to [Run Cube CLI commands](#cube-cli-commands).

1. Go to `Tools | STM32 Cube CLI | Convert to STM32 Cube Project`.

![Tools menu with the STM32 Cube CLI submenu open, showing the Open STM32 Cube CLI Terminal and Convert to STM32 Cube Project actions.](https://resources.jetbrains.com/help/img/idea/2026.2/bundles-lock.store.json`.

> **Tip:**
> A project is recognized as a Cube project when it has a `.settings` directory with these two files. Listing a bundle there does not make the project use it: the tool also needs to be referenced in the project itself.

### Install project bundles

In a Cube project, two more actions become available in `Tools | STM32 Cube CLI`:

Install Project Bundles
: Installs the bundles that are locked by Cube CLI but missing on your machine.

Install Project Bundles to All Environments
: Installs the missing bundles on every machine that your project uses. This action appears when the CMake profiles target different machines, for example a local and a remote toolchain.

A missing bundle does not necessarily break the CMake reload: Cube CLI looks for an equivalent tool and uses it instead. In this case, the CMake reload terminal shows a warning with a quick-fix that installs the required bundles.

> **Note:**
> The CMake bundle is always required for the integration, even when the project does not lock it. Without this bundle, the CMake reload fails, and the error in the CMake reload terminal includes a quick-fix that installs the CMake bundle globally.

### Run Cube CLI commands

To manage the bundles of an existing project, use the Cube CLI commands. Go to `Tools | STM32 Cube CLI | Open STM32 Cube CLI Terminal` to open a terminal in which `cube` is available for the environment of the selected CMake profile. You can also open it from the tab drop-down list in the Terminal tool window.

cube bundle list-online
: Lists the bundles available for download and their versions.

cube bundle show
: `cube bundle show <bundle>` shows the details of a bundle: the environment variables that it sets, its entries in the `PATH` variable, and the commands that it provides.

cube bundle init
: `cube bundle init --project <bundles>` converts the current project into a Cube project and locks the specified bundles in it.

cube bundle install
: `cube bundle install --project <bundles>` installs the specified bundles and locks them in the project. Omit `--project` to install the bundles globally.

cube bundle remove
: `cube bundle remove --project <bundles>` removes the specified bundles from the tools locked in the project. Omit `--project` to uninstall the bundles globally.

In these commands, `<bundles>` uses the `bundle_name@version` format. For example, `gnu-tools-for-stm32@14.3.1+st.2`.

## See also

### JetBrains Blog Posts

[Working With STM32 Arm TrustZone-Based Projects in CLion](https://blog.jetbrains.com/clion/2026/03/working-with-stm32-arm-trustzone-in-clion/) [CLion for embedded development](https://blog.jetbrains.com/clion/2016/06/clion-for-embedded-development/) [CLion for embedded development, part II](https://blog.jetbrains.com/clion/2017/12/clion-for-embedded-development-part-ii/) [CLion for embedded development, part III](https://blog.jetbrains.com/clion/2019/02/clion-2019-1-eap-clion-for-embedded-development-part-iii/)

### External Links

[Embedded Development in CLion FAQs](https://intellij-support.jetbrains.com/hc/en-us/articles/4405160320274-Embedded-Development-in-CLion) [PEmicro tools in CLion setup guide](https://www.pemicro.com/blog/index.cfm?post_id=245)