CLion integration fails to source export.sh when non-system Python is in PATH (conda/homebrew), leading to CMake project loading failed (IDFGH-16650)

[shengt25]

Answers checklist.

• I have read the documentation ESP-IDF Programming Guide and the issue is not addressed there.
• I have updated my IDF branch (master or release) to the latest version and checked that the issue is present there.
• I have searched the issue tracker for a similar issue and not found a similar issue.

IDF version.

v5.5.1

Operating System used.

macOS

How did you build your project?

CLion IDE

If you are using Windows, please specify command line type.

None

What is the expected behavior?

Following the official CLion tutorial (https://developer.espressif.com/blog/clion/), the project should load successfully in CLion after configuring the environment file with export.sh.

What is the actual behavior?

When using conda/miniconda for Python management, export.sh fails to detect the correct Python virtual environment in CLion, causing CMake project loading to fail with:

CMake Error at CMakeLists.txt:6 (include):
  include could not find requested file:

    /tools/cmake/project.cmake


CMake Error at CMakeLists.txt:8 (idf_build_set_property):
  Unknown CMake command "idf_build_set_property".


-- Configuring incomplete, errors occurred!

This occurs because export.sh detects system Python instead of conda Python. See More Information for details

Steps to reproduce.

1. Install conda/miniconda with Python (such as 3.13) as base environment
2. Make sure the default Python is now the one from conda/miniconda.
3. Follow the ESP-IDF setup steps, run install.sh in terminal, this creates $IDF_TOOLS_PATH/python_env/idf5.5_py3.13_env
4. Verify it works in terminal: source export.sh, successful
5. Follow the CLion tutorial to set environment file to export.sh in Toolchain settings
6. Try open and load a project in CLion

Expected: Project loads successfully
Actual: CMake error (see above)

Build or installation Logs.

Diagnostic report archive.

No response

More Information.

Why this happens:

CLion (and most IDEs) don't load user shell configurations like ~/.zshrc by design. When CLion executes export.sh, conda's PATH is not available, so export.sh falls back to system Python which has a different version than the one used during installation.

In the Clion environment file loading process, export.sh detects system Python (in my case, /usr/bin/python3 v3.9.6) instead of conda Python (in my case $HOME/miniconda3/bin/python v3.13.2).

Therefore, it tries to find the wrong path $IDF_TOOLS_PATH/python_env/idf5.5_py3.9_env while the correct one should be $IDF_TOOLS_PATH/python_env/idf5.5_py3.13_env.

This cause the following process fail and project doesn't setup correctly.

Debug findings:

I temporarily modified export.sh to add logging to track the issue:

• Added echo statements to log Python detection results to $HOME/clion-idf-debug.log
• Found that after CLion load the project, the log recorded that it detected /usr/bin/python3 (version 3.9.6)
• Found that it was trying to access $IDF_TOOLS_PATH/python_env/idf5.5_py3.9_env (which doesn't exist)
  While the correct path created during installation was $IDF_TOOLS_PATH/python_env/idf5.5_py3.13_env

Workaround:

Create a wrapper script and use it as the environment file in CLion. For example if user is using miniconda installed in $HOME/miniconda3:

export PATH="$HOME/miniconda3/bin:$PATH"
source $IDF_PATH/export.sh

Suggested solutions:

Option 1: Update the CLion tutorial documentation to include a note about this limitation. That user need to create a wrapper script that initializes your Python environment before sourcing export.sh

Option 2: Have install.sh record the Python path during installation, and make export.sh export this recorded path first. And provide a command to update this recorded path when users change their Python environment.

Also, Maybe add some diagnostic messages in CMake scripts when something goes wrong, showing what is missing and environment variables that ESP-IDF requires.

[shengt25]

After more testing, this issue is not limited to conda. It also affects Python installed via Homebrew.
In this case, adding export PATH="/opt/homebrew/bin:$PATH" in the wrapper also solve the problem.

It seems that installing ESP-IDF with any Python in PATH before system Python prevents CLion toolchain environment file loading.

[shengt25]

Also, I found that having conda active during ESP-IDF installation can also cause GDB to crash with segmentation faults when loading ELF files.

The solution is to disable conda before running ./install.sh, then re-enable it after installation completes. This is related to issue #16219. And the solution to segmentation faults is #16219 (comment)

The conda environment conflict affects not just CLion integration, but also somehow corrupts the GDB toolchain during installation.

[dobairoland]

Hi @shengt25. Yes, you are right. At the moment only system Pythons are supported. Aliasing is also not working.

I'd like to add one more workaround which personally I use. I create a symbolic link named as python3 from a user bin directory I already have in the path (~/.local/bin or ~/bin) and link the desired Python interpreter. This way one doesn't need to have any wrappers and the setup is permanent and for the given user only.

There is another workaround. IDF_PYTHON_ENV_PATH environment variable can be set to any directory the install script created. The export script will use it. This is documented here: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-tools.html

We will either improve this or update the ESP-IDF documentation with this limitation and workarounds.

Update the CLion tutorial documentation to include a note about this limitation.

I'm sorry but I'm not aware what documentation you are referring to. I don't think we (Espressif Systems) maintain any CLion documentation.

[shengt25]

Hi @shengt25. Yes, you are right. At the moment only system Pythons are supported. Aliasing is also not working.

I'd like to add one more workaround which personally I use. I create a symbolic link named as python3 from a user bin directory I already have in the path (~/.local/bin or ~/bin) and link the desired Python interpreter. This way one doesn't need to have any wrappers and the setup is permanent and for the given user only.

There is another workaround. IDF_PYTHON_ENV_PATH environment variable can be set to any directory the install script created. The export script will use it. This is documented here: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-tools.html

We will either improve this or update the ESP-IDF documentation with this limitation and workarounds.

Update the CLion tutorial documentation to include a note about this limitation.

I'm sorry but I'm not aware what documentation you are referring to. I don't think we (Espressif Systems) maintain any CLion documentation.

Hi, thanks for the quick response and the additional workarounds! The symbolic link approach and IDF_PYTHON_ENV_PATH variable are both great solutions.

About the "CLion documentation", sorry for the confusion. I was referring to the tutorial blog post at https://developer.espressif.com/blog/clion/. I understand it's a blog article rather than official documentation.

Thanks for looking into this! Hope these workarounds help others who run into the same issue with in Clion, or the related GDB segmentation fault issue when installing with conda active.