---

应用场景：

ESP32-WSL开发环境搭建过程中遇到的问题及解决方案

---

问题1描述:

ESP-IDF wsl 开发环境搭建完毕后，执行激活命令失败。

comeon@CARtech-jg:~/esp-idf$ . ./export.sh
Checking "python3" ...
Python 3.10.12
"python3" has been detected
error: Unable to import the rich module: No module named 'rich'. Please execute the install script.ERROR: Activation script failed
Command '['/home/comeon/.espressif/python_env/idf5.5_py3.10_env/bin/python', '/home/comeon/esp-idf/tools/export_utils/activate_venv.py', '--export', '--shell', 'bash']' returned non-zero exit status 1.
To view detailed debug information, set ESP_IDF_EXPORT_DEBUG=1 and run the export script again.

---

原因分析：

这个错误提示表明 ESP-IDF 环境激活失败，原因是缺少rich Python 模块。可以按照以下步骤解决：

首先确保你在 ESP-IDF 的 Python 虚拟环境中安装rich模块：

# 激活ESP-IDF的Python虚拟环境
source ~/.espressif/python_env/idf5.5_py3.10_env/bin/activate# 安装rich模块
pip install rich

执行第一个命令时，报错：

comeon@CARtech-jg:~/esp-idf$ source ~/.espressif/python_env/idf5.5_py3.10_env/bin/activate
-bash: /home/comeon/.espressif/python_env/idf5.5_py3.10_env/bin/activate: No such file or directory

从错误信息来看，ESP-IDF 对应的 Python 虚拟环境目录 idf5.5_py3.10_env 不存在，可能是之前的 ESP-IDF 工具链安装不完整，或虚拟环境未成功创建导致的。

---

解决方案：

可按以下步骤重新修复环境，解决激活问题：

先检查 ESP-IDF 工具链是否安装完整

进入 esp-gitee-tools 目录（之前下载的工具目录，若忘记路径可通过 find ~ -name “esp-gitee-tools” 查找）：

cd ~/esp-gitee-tools  # 若路径不同，替换为实际的esp-gitee-tools目录

重新执行 ESP-IDF 的安装脚本，补全工具链和虚拟环境：

export EGT_PATH=$(pwd)  # 设定工具路径变量
cd ~/esp-idf  # 进入ESP-IDF主目录
$EGT_PATH/install.sh  # 重新运行安装脚本

安装过程中会自动创建对应 Python 版本的虚拟环境（如 idf5.5_py3.10_env），并安装依赖模块。若出现 “是否继续” 的提示，输入 y 确认，等待安装完成（需保证网络稳定，避免中断）。

设定工具路径变量一切正常：

执行重新运行安装脚本后又报错：

comeon@CARtech-jg:~/esp-idf$ $EGT_PATH/install.sh
Detecting Python interpreter
Checking "python3" ...
Python 3.10.12
"python3" has been detected
Installing ESP-IDF tools
Updating /home/comeon/.espressif/idf-env.json
Selected targets are: esp32c3, esp32p4, esp32c2, esp32c6, esp32s2, esp32h2, esp32c61, esp32h21, esp32s3, esp32h4, esp32c5, esp32
Current system platform: linux-amd64
Installing tools: xtensa-esp-elf-gdb, riscv32-esp-elf-gdb, xtensa-esp-elf, riscv32-esp-elf, esp32ulp-elf, openocd-esp32, esp-rom-elfs
Skipping xtensa-esp-elf-gdb@16.2_20250324 (already installed)
Skipping riscv32-esp-elf-gdb@16.2_20250324 (already installed)
Skipping xtensa-esp-elf@esp-14.2.0_20241119 (already installed)
Skipping riscv32-esp-elf@esp-14.2.0_20241119 (already installed)
Skipping esp32ulp-elf@2.38_20240113 (already installed)
Skipping openocd-esp32@v0.12.0-esp32-20250226 (already installed)
Skipping esp-rom-elfs@20241011 (already installed)
Installing Python environment and packages
Python 3.10.12
/home/comeon/.espressif/python_env/idf5.5_py3.10_env/bin/python: No module named pip
WARNING: pip is not available in the existing virtual environment, new virtual environment will be created.
WARNING: Removing the existing Python environment in /home/comeon/.espressif/python_env/idf5.5_py3.10_env
Creating a new Python environment in /home/comeon/.espressif/python_env/idf5.5_py3.10_env
The virtual environment was not created successfully because ensurepip is not
available.  On Debian/Ubuntu systems, you need to install the python3-venv
package using the following command.apt install python3.10-venvYou may need to use sudo with that command.  After installing the python3-venv
package, recreate your virtual environment.Failing command: /home/comeon/.espressif/python_env/idf5.5_py3.10_env/bin/python3Traceback (most recent call last):File "/home/comeon/esp-idf/tools/idf_tools.py", line 3572, in <module>main(sys.argv[1:])File "/home/comeon/esp-idf/tools/idf_tools.py", line 3562, in mainaction_func(args)File "/home/comeon/esp-idf/tools/idf_tools.py", line 2830, in action_install_python_envsubprocess.check_call(File "/usr/lib/python3.10/subprocess.py", line 369, in check_callraise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['/usr/bin/python3', '-m', 'venv', '/home/comeon/.espressif/python_env/idf5.5_py3.10_env']' returned non-zero exit status 1.

原因分析

从报错信息可以明确，问题根源是 Ubuntu 系统缺少python3.10-venv包—— 这是 Python 3.10 创建虚拟环境必需的组件，没有它会导致 ESP-IDF 无法生成idf5.5_py3.10_env虚拟环境，进而触发后续的pip缺失和激活失败。

解决方法：

第一步：安装python3.10-venv包（核心修复）

sudo apt update && sudo apt install -y python3.10-venv

udo apt update：更新软件源列表，确保能找到最新的python3.10-venv包；
sudo apt install -y python3.10-venv：自动确认安装（-y参数），避免手动输入y确认。

comeon@CARtech-jg:~/esp-idf$ sudo apt update && sudo apt install -y python3.10-venv
[sudo] password for comeon:
Get:1 http://security.ubuntu.com/ubuntu jammy-security InRelease [129 kB]
Hit:2 http://archive.ubuntu.com/ubuntu jammy InRelease
Get:3 http://archive.ubuntu.com/ubuntu jammy-updates InRelease [128 kB]
Get:4 http://archive.ubuntu.com/ubuntu jammy-backports InRelease [127 kB]
Get:5 http://security.ubuntu.com/ubuntu jammy-security/main amd64 Packages [2595 kB]
Get:6 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 Packages [2843 kB]
Get:7 http://archive.ubuntu.com/ubuntu jammy-updates/universe amd64 Packages [1227 kB]
Get:8 http://archive.ubuntu.com/ubuntu jammy-updates/universe Translation-en [304 kB]
Get:9 http://security.ubuntu.com/ubuntu jammy-security/universe amd64 Packages [994 kB]
Fetched 8347 kB in 8s (1060 kB/s)
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
222 packages can be upgraded. Run 'apt list --upgradable' to see them.
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:libpython3.10 libpython3.10-dev libpython3.10-minimal libpython3.10-stdlib python3-pip-whl python3-setuptools-whlpython3.10 python3.10-dev python3.10-minimal
Suggested packages:python3.10-doc binfmt-support
The following NEW packages will be installed:python3-pip-whl python3-setuptools-whl python3.10-venv
The following packages will be upgraded:libpython3.10 libpython3.10-dev libpython3.10-minimal libpython3.10-stdlib python3.10 python3.10-devpython3.10-minimal
7 upgraded, 3 newly installed, 0 to remove and 215 not upgraded.
Need to get 15.1 MB of archives.
After this operation, 2894 kB of additional disk space will be used.
Get:1 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 python3.10-dev amd64 3.10.12-1~22.04.11 [508 kB]
Get:2 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 libpython3.10-dev amd64 3.10.12-1~22.04.11 [4764 kB]
Get:3 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 libpython3.10 amd64 3.10.12-1~22.04.11 [1949 kB]
Get:4 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 python3.10 amd64 3.10.12-1~22.04.11 [508 kB]
Get:5 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 libpython3.10-stdlib amd64 3.10.12-1~22.04.11 [1850 kB]
Get:6 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 python3.10-minimal amd64 3.10.12-1~22.04.11 [2264 kB]
Get:7 http://archive.ubuntu.com/ubuntu jammy-updates/main amd64 libpython3.10-minimal amd64 3.10.12-1~22.04.11 [815 kB]
Get:8 http://archive.ubuntu.com/ubuntu jammy-updates/universe amd64 python3-pip-whl all 22.0.2+dfsg-1ubuntu0.6 [1680 kB]
Get:9 http://archive.ubuntu.com/ubuntu jammy-updates/universe amd64 python3-setuptools-whl all 59.6.0-1.2ubuntu0.22.04.3 [789 kB]
Get:10 http://archive.ubuntu.com/ubuntu jammy-updates/universe amd64 python3.10-venv amd64 3.10.12-1~22.04.11 [5726 B]
Fetched 15.1 MB in 15s (1028 kB/s)
(Reading database ... 31282 files and directories currently installed.)
Preparing to unpack .../0-python3.10-dev_3.10.12-1~22.04.11_amd64.deb ...
Unpacking python3.10-dev (3.10.12-1~22.04.11) over (3.10.12-1~22.04.9) ...
Preparing to unpack .../1-libpython3.10-dev_3.10.12-1~22.04.11_amd64.deb ...
Unpacking libpython3.10-dev:amd64 (3.10.12-1~22.04.11) over (3.10.12-1~22.04.9) ...
Preparing to unpack .../2-libpython3.10_3.10.12-1~22.04.11_amd64.deb ...
Unpacking libpython3.10:amd64 (3.10.12-1~22.04.11) over (3.10.12-1~22.04.9) ...
Preparing to unpack .../3-python3.10_3.10.12-1~22.04.11_amd64.deb ...
Unpacking python3.10 (3.10.12-1~22.04.11) over (3.10.12-1~22.04.9) ...
Preparing to unpack .../4-libpython3.10-stdlib_3.10.12-1~22.04.11_a