【Ubuntu】系统下VScode配置ESP-IDF插件esp-clang和Python 3版本报错问题

引言

使用 Ubuntu 系统配置 ESP32 的 VScode 环境的时候遇到了两个问题，会导致 VScode 中按下Shift+Ctrl+P使用ESP-IDF: Add VS Code Configuration Folder命令（添加配置的文件夹到 VScode 中，使得 VScode 可以找到文件路径）无效，并出现/tools/idf_py_actions/hints.yml does not exist.提示，下面是两个问题：

一、
Command failed: /usr/bin/python3 /home/shf/esp32/
esp-idf/tools/idf_tools.py install esp-clang

二、
non zero exit code 1 ESP-IDF supports Python 3.9 or newer 
but you are using Python 3.8.10. Please upgrade your installation 
as described in the documentation.

解决办法

问题一

Command failed: /usr/bin/python3 /home/shf/esp32/
esp-idf/tools/idf_tools.py install esp-clang

这个错误是因为 esp-clang 工具安装失败，通常和依赖缺失、网络问题、权限不足有关。

步骤 1

检查并安装系统依赖：

sudo apt update

sudo apt install -y clang libstdc++6 zlib1g-dev

步骤 2

如果之前安装过 esp-clang 但文件损坏，先清理残留：

rm -rf ~/.espressif/tools/esp-clang  # 删除旧的esp-clang工具

步骤 3

重新安装

cd /home/shf/esp32/esp-idf  # 进入esp-idf目录

./tools/idf_tools.py install esp-clang  # 重新安装esp-clang

步骤 4

验证安装并刷新环境

. ./export.sh  # 激活esp-idf环境

esp-clang --version  # 验证是否安装成功（若输出版本则正常）

如果仍失败

cd /home/shf/esp32/esp-idf

./install.sh  # 重新安装所有esp-idf依赖

source ./export.sh

问题二

non zero exit code 1 ESP-IDF supports Python 3.9 or newer 
but you are using Python 3.8.10. Please upgrade your installation 
as described in the documentation.

问题的核心是：系统中虽安装了 Python 3.9，但 ESP-IDF 脚本仍识别到默认 Python 版本为 3.8.10，本质是 Python 版本优先级 / 环境变量配置问题。

步骤 1

# 列出系统中所有Python 3版本
ls /usr/bin/python3*  
# 或直接查找Python 3.9可执行文件
which python3.9  

输出：

/usr/bin/python3  /usr/bin/python3.8  /usr/bin/python3.8-config  /usr/bin/python3.9  /usr/bin/python3.9-config  /usr/bin/python3-config

或

/home/shf/.espressif/python_env/idf5.5_py3.9_env/bin/python3.9

步骤 2

# 替换成你查到的Python 3.9路径，执行安装指令
/usr/bin/python3.9 /home/shf/esp32/esp-idf/tools/idf_tools.py install esp-clang

步骤 3

通过update-alternatives配置 Python 3 优先级，让系统默认使用 3.9：

# 1. 注册Python 3.8和3.9到系统备选列表
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.8 10
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.9 20

# 2. 选择默认Python 3版本（输入对应数字选3.9）
sudo update-alternatives --config python3

输出：

  Selection    Path                Priority   Status
------------------------------------------------------------
  0            /usr/bin/python3.9   20        auto mode
  1            /usr/bin/python3.8   10        manual mode
* 2            /usr/bin/python3.9   20        manual mode

Press <enter> to keep the current choice[*], or type selection number:
要维持当前值[*]请按回车键，或者键入选择的编号：2

步骤 4

# 验证默认Python 3版本（应输出3.9.x）
python3 --version  
# 重新执行esp-clang安装
cd /home/shf/esp32/esp-idf
./tools/idf_tools.py install esp-clang

博客导航

博客导航