---

應用場景：

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