# ESP-IDF

> **Note:**
> This article will be updated soon. In the meantime, follow the [Working with ESP-IDF in CLion](https://developer.espressif.com/blog/clion/) tutorial, which explains our current approach to working with ESP-IDF projects in the IDE. The tutorial provides detailed instructions on how to configure a project, build an application, flash it to a board, and debug it.

[ESP-IDF](https://github.com/espressif/esp-idf) is the official development framework for the [ESP32 and ESP32-S Series SoCs](https://www.espressif.com/en/products/socs). This article is an introductory guide for working with ESP-IDF in CLion.

Some steps replicate the [ESP-IDF Get Started](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#step-2-get-esp-idf) guide. Examples below are given for the case of macOS, Windows-specific instructions are marked accordingly.

Procedure: Prepare the environment

1. Make sure you have a recent [Python](https://www.python.org/downloads/) version, [pip](https://packaging.python.org/tutorials/installing-packages/), and [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed on your system.

2. Using your system terminal, create a directory for ESP-IDF and clone the official [repository](https://github.com/espressif/esp-idf):

```CONSOLE
mkdir -p ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
```

ESP-IDF will be downloaded into `~/esp/esp-idf`.

3. In the same shell, install the tools:

```CONSOLE
cd esp-idf
./install.sh
```

4. On Windows, make sure the USB bridge of the ESP-32 board is identified correctly. You can check that in the Device Manager.

> **Tip:**
> Watch [Developing for ESP32 With CLion on Windows: Preparation](https://www.youtube.com/watch?v=M6fa7tzZdLw&t=21s) for video instructions.

Procedure: Set up a sample project using CLion's terminal

1. In CLion, go to `File | Open` in the main menu and select the `~/esp/esp-idf` directory .

At this point, project loading might fail due to the Current directory '../esp/esp-idf' is not buildable... error.

2. Open CLion's built-in terminal (`View | Tool Windows | Terminal` or `Alt+F12` (Windows), `⌥ F12` (macOS), `⌥ F12` (IntelliJ IDEA Classic (macOS)), `⌘ ⌃ T` (macOS System Shortcuts), `Alt+F12` (XWin), `Alt+F12` (GNOME), `Alt+F12` (KDE), `Alt+F12` (Emacs), `Alt+F12` (Sublime Text), `⌥ F12` (Sublime Text (macOS)), `⌥ F12` (Xcode), `Ctrl+Alt+1` (Visual Studio), `⌘ ⌃ 1` (Visual Studio (macOS)), `Ctrl+Alt+1` (ReSharper), `⌘ ⌃ 1` (ReSharper (macOS)), `Alt+F12` (QtCreator), `⌥ F12` (QtCreator (macOS)), `Alt+F12` (NetBeans), `Alt+F12` (Eclipse), `⌥ F12` (Eclipse (macOS))).

3. Set up the environment variables by running `. $HOME/esp/esp-idf/export.sh`:

![The result of setting ESP-IDF environment](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_espidf_environment.png)

4. Let's configure the hello_world project from the `examples/get-started` directory. The following commands set ESP32 chip as the target and run the menuconfig configuration utility:

```CONSOLE
cd $IDF_PATH/examples/get-started/hello_world
idf.py set-target esp32
idf.py menuconfig
```

The last command opens the configuration menu. As the hello_world project we are using will run with default configuration, you don't need to set it up in this menu.

![Configuration menu](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_espidf_configmenu.png)

Step out from the menu, and check the configuration is complete.

5. Now we can build hello_world by running `idf.py build`:

![Build result](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_espidf_buildresult.png)

Next up, you can continue working with the project in CLion using the terminal. This will not require additional CMake configuration. Alternatively, you can set up CMake so that the project can be loaded, built and run without the command line (see below).

## Configure an ESP CMake project in CLion

Procedure: Open the Hello-world project

1. In the main menu, go to `File | Open` and select the `esp/esp-idf/examples/get-started/hello_world` folder.

2. Click Open as Project and [trust the sources](project-security.html).

At this point, project loading might fail.

> **Tip:**
> If you are working on Windows, go to `Settings | Build, Execution, Deployment | Toolchain` and set up the toolchain for your project. For more information, refer to [Tutorial: Configure CLion on Windows](quick-tutorial-on-configuring-clion-on-windows.html).

### Source the environment

Use the toolchain settings to specify the ESP-IDF environment script.

You will need either one or two environment files from the ESP-IDF installation. Two files are required for the case of Python virtual environment.

Procedure: Source the environment script (macOS example)

1. Go to `Settings | Build, Execution, Deployment | Toolchain`.

2. Click Add environment next to the Name field, then click From file.

3. Navigate to `esp/esp-idf` and select `export.sh`:

![Setting the toolchain environment script](https://resources.jetbrains.com.cn/help/img/idea/2026.2/cl_espidf_toolchain_envscript.png)

4. Save the toolchain settings.

5. The project will be reloaded automatically. In case of errors, call `Tools | CMake | Reset Cache and Reload project` from the main menu.

Procedure: Source the environment using a custom script (Windows example)

On Windows, two files are required to set up the ESP-IDF environment. To automate this, you can create a simple script that will load them both and use it as the toolchain environment file.

1. Create a script file in the project folder. For example, `espidf_source.bat`.

2. Customize the following lines and add them to your script:

```BASH
@call C:\Espressif\python_env\idf5.0_py3.8_env\Scripts\activate.bat
@call C:\Espressif\frameworks\esp-idf-v5.0-2\export.bat
```

3. Go to `Settings | Build, Execution, Deployment | Toolchain`.

4. Click Add environment next to the Name field, then click From file.

5. Select the newly created file.

6. Save the toolchain settings.

7. The project will be reloaded automatically. In case of errors, call `Tools | CMake | Reset Cache and Reload project` from the main menu.

Procedure: Build the project

1. CLion will automatically create [run/debug configurations](run-debug-configuration.html) for all the detected CMake targets.

To build the project, select app in the configuration switcher, then click the hammer icon or press `Ctrl + F9` to run [build](build-actions.html) for this configuration.

2. At this point, all CLion code insight features are available for your ESP project. Watch [Developing for ESP32 With CLion on Windows: Code insight](https://www.youtube.com/watch?v=M6fa7tzZdLw&t=399s) for some examples.

Procedure: Flash and monitor an ESP-32 chip in CLion

> **Tip:**
> For video instructions, watch [Developing for ESP32 With CLion on Windows: Flashing and monitoring your ESP-32 chip](https://www.youtube.com/watch?v=M6fa7tzZdLw&t=482s)

1. Select flash in the configuration switcher and click the hammer icon or press `Ctrl + F9` to build it.

In the build output, you can check the percentage indicator for chip flashing.

2. Select the monitor configuration and build it. If you get an error that serial port cannot be opened, then do the following:

1. Open the Device Manager and check the port that is used by your ESP device.

2.  Add one more variable to the Environment variables in CMake settings: `ESPPORT`. Set the value to the port, for example, `COM3`.

3. After the project is reloaded, build the monitor configuration again. The ESP-32 chip should report back as expected.

## Troubleshooting (Windows)

If you are getting the `Git executable not found` error on Windows, make sure that Git is installed into a location discoverable by ESP-IDF's `find_package(Git)` command.

To workaround that, add the `GIT` environment variable with the full path to the `git.exe` binary. You can do that by modifying `esp/idf/tools/cmake/git_submodules.cmake`. In the first line, change `find_package(Git)` to the following:

```CMAKE
if (DEFINED ENV{GIT})
    execute_process(COMMAND $ENV{GIT} --version
    OUTPUT_VARIABLE git_version
    ERROR_QUIET
    OUTPUT_STRIP_TRAILING_WHITESPACE)
    if (git_version MATCHES "^git version [0-9]")
        string(REPLACE "git version " "" GIT_VERSION_STRING "${git_version}")
        set(GIT_FOUND True)
        set(GIT_EXECUTABLE $ENV{GIT})
    endif()
    unset(git_version)
else()
    find_package(Git)
endif ()
```

## See also

### External Links

[CLion blog: Developing for ESP32 With CLion on Windows](https://blog.jetbrains.com/clion/2021/09/developing-for-esp32-with-clion-on-windows/) [Video: Developing for ESP32 With CLion on Windows](https://www.youtube.com/watch?v=M6fa7tzZdLw)