From c2a568f6efbcf4753e05d66c87302472213d50e5 Mon Sep 17 00:00:00 2001
From: garywill <garywill@disroot.org>
Date: Sun, 16 Nov 2025 13:54:40 +0800
Subject: [PATCH 1/8] feat(tools): allow to specify python binary by ESP_PYTHON
 environment variable

---
 docs/en/api-guides/tools/idf-tools.rst       |  2 +-
 docs/en/get-started/linux-macos-setup.rst    |  2 ++
 docs/zh_CN/api-guides/tools/idf-tools.rst    |  2 +-
 docs/zh_CN/get-started/linux-macos-setup.rst |  2 ++
 tools/detect_python.fish                     | 15 ++++++++---
 tools/detect_python.sh                       | 26 +++++++++++++-------
 6 files changed, 34 insertions(+), 15 deletions(-)

diff --git a/docs/en/api-guides/tools/idf-tools.rst b/docs/en/api-guides/tools/idf-tools.rst
index 9006b2f7a31a..f7041d20c3e0 100644
--- a/docs/en/api-guides/tools/idf-tools.rst
+++ b/docs/en/api-guides/tools/idf-tools.rst
@@ -161,7 +161,7 @@ Shell-specific user-facing installation scripts are provided in the root directo
 * ``install.sh`` for Bash
 * ``install.fish`` for Fish
 
-Apart from downloading and installing the tools in ``IDF_TOOLS_PATH``, these scripts prepare a Python virtual environment, and install the required packages into that environment.
+Apart from downloading and installing the tools in ``IDF_TOOLS_PATH``, these scripts prepare a Python virtual environment, and install the required packages into that environment. If you want to specify a particular Python for ESP-IDF, you need to set environment variable ``ESP_PYTHON`` before installation and each time before use. For example ``export ESP_PYTHON=/opt/bin/python3.13``.
 
 These scripts accept optionally a comma-separated list of chip targets and ``--enable-*`` arguments for enabling features. These arguments are passed to the ``idf_tools.py`` script which stores them in ``idf-env.json``. Therefore, chip targets and features can be enabled incrementally.
 
diff --git a/docs/en/get-started/linux-macos-setup.rst b/docs/en/get-started/linux-macos-setup.rst
index 7848bf6e6a99..1d6b62cf4e55 100644
--- a/docs/en/get-started/linux-macos-setup.rst
+++ b/docs/en/get-started/linux-macos-setup.rst
@@ -116,6 +116,8 @@ To install supported Python 3 on macOS:
 
     During installation, the install script will check for supported Python versions on your system and select the oldest version that meets the minimum requirement.
 
+If you want to specify a particular Python for ESP-IDF, you need to set environment variable ``ESP_PYTHON`` before installation and each time before use. For example ``export ESP_PYTHON=/opt/bin/python3.13``.
+    
 .. _get-started-get-esp-idf:
 
 Step 2. Get ESP-IDF
diff --git a/docs/zh_CN/api-guides/tools/idf-tools.rst b/docs/zh_CN/api-guides/tools/idf-tools.rst
index 8cb37d5946bf..2cee603fb69b 100644
--- a/docs/zh_CN/api-guides/tools/idf-tools.rst
+++ b/docs/zh_CN/api-guides/tools/idf-tools.rst
@@ -161,7 +161,7 @@ ESP-IDF 的根目录中提供了针对不同 shell 的用户安装脚本，包
 * ``install.sh`` 适用于 Bash
 * ``install.fish`` 适用于 Fish
 
-这些脚本除了下载和安装 ``IDF_TOOLS_PATH`` 中的工具外，还会准备一个 Python 虚拟环境，并在此虚拟环境中安装所需软件包。
+这些脚本除了下载和安装 ``IDF_TOOLS_PATH`` 中的工具外，还会准备一个 Python 虚拟环境，并在此虚拟环境中安装所需软件包。如果要指定 ESP-IDF 使用特定的 Python ，则需要在安装之前及每次使用之前设置环境变量 ``ESP_PYTHON``，例如 ``export ESP_PYTHON=/opt/bin/python3.13``。
 
 为启用相应功能，这些脚本可以选择性地接受一组以逗号分隔的芯片目标列表及 ``--enable-*`` 参数，这类参数会传递给 ``idf_tools.py`` 脚本，并由该脚本将这类参数存储在 ``idf-env.json`` 中，从而逐步启用芯片目标及功能。
 
diff --git a/docs/zh_CN/get-started/linux-macos-setup.rst b/docs/zh_CN/get-started/linux-macos-setup.rst
index abe4bb64984b..759c337fcbab 100644
--- a/docs/zh_CN/get-started/linux-macos-setup.rst
+++ b/docs/zh_CN/get-started/linux-macos-setup.rst
@@ -115,6 +115,8 @@ Apple M1 用户
 .. note::
 
     安装过程中，安装脚本 (install.sh) 会检查系统中已安装的 Python 版本，并在所有符合最低要求的版本中，选择最早的版本使用。
+    
+如果要指定 ESP-IDF 使用特定的 Python ，则需要在安装之前及每次使用之前设置环境变量 ``ESP_PYTHON``，例如 ``export ESP_PYTHON=/opt/bin/python3.13``。
 
 .. _get-started-get-esp-idf:
 
diff --git a/tools/detect_python.fish b/tools/detect_python.fish
index 8e9947f3a8a4..94afa02d59db 100644
--- a/tools/detect_python.fish
+++ b/tools/detect_python.fish
@@ -5,20 +5,27 @@
 set OLDEST_PYTHON_SUPPORTED_MAJOR 3
 set OLDEST_PYTHON_SUPPORTED_MINOR 10
 
-set -x ESP_PYTHON python
+if test -z "$ESP_PYTHON"
+    set PYTHON_CANDIDATES python3 python python3.10 python3.11 python3.12 python3.13
+else
+    echo "Reading ESP_PYTHON from environment: \"$ESP_PYTHON\""
+    set PYTHON_CANDIDATES $ESP_PYTHON
+end
+set -e ESP_PYTHON  # Unset it. Will assign after candidate check
 
-for p_cmd in python3 python python3.10 python3.11 python3.12 python3.13;
+for p_cmd in $PYTHON_CANDIDATES
     $p_cmd --version >/dev/null 2>&1; or continue
     echo "Checking \"$p_cmd\" ..."
 
     $p_cmd -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);"; or continue
     $p_cmd -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);"; or continue
 
-    set ESP_PYTHON $p_cmd
+    set -x ESP_PYTHON $p_cmd
     break
 end
+set -e PYTHON_CANDIDATES
 
-test -n "$ESP_PYTHON"; or echo "Python $OLDEST_PYTHON_SUPPORTED_MAJOR.$OLDEST_PYTHON_SUPPORTED_MINOR+ is not installed! Please see the documentation for how to install it."
+test -n "$ESP_PYTHON"; or echo "Python $OLDEST_PYTHON_SUPPORTED_MAJOR.$OLDEST_PYTHON_SUPPORTED_MINOR+ is not installed! Please see the documentation for how to install it." >&2
 test -n "$ESP_PYTHON"; or exit 1
 
 $ESP_PYTHON --version
diff --git a/tools/detect_python.sh b/tools/detect_python.sh
index 3f84a9b91ef8..4290c5df19ee 100644
--- a/tools/detect_python.sh
+++ b/tools/detect_python.sh
@@ -3,28 +3,36 @@
 # This is a helper script for detecting Python executables in the PATH. It is intended to be used for determining
 # which Python should be used with idf_tools.py for installing tools and exporting environment variables.
 #
-# 1. The script is looking for python version same or greater than minimal required version on path
+# 1. If environment variable ESP_PYTHON already set, script uses that python binary, otherwise, looks for python version same or greater than minimal required version on path
 # 2. If required version of python is found it is assigned to environmental variable `ESP_PYTHON`
 # 3. If required version of python is not found, script will fail
 
 OLDEST_PYTHON_SUPPORTED_MAJOR=3
 OLDEST_PYTHON_SUPPORTED_MINOR=10
 
-ESP_PYTHON=python
 
-for p_cmd in python3 python python3.10 python3.11 python3.12 python3.13; do
-    $p_cmd --version >/dev/null 2>&1 || continue
+if [[ -z "$ESP_PYTHON" ]]; then
+    PYTHON_CANDIDATES=(python3 python python3.10 python3.11 python3.12 python3.13)
+else
+    echo "Reading ESP_PYTHON from environment: \"$ESP_PYTHON\""
+    PYTHON_CANDIDATES=("$ESP_PYTHON")
+fi
+ESP_PYTHON=  # Unset it. Will assign after candidate check
+
+for p_cmd in "${PYTHON_CANDIDATES[@]}"; do
+    "$p_cmd" --version >/dev/null 2>&1 || continue
     echo "Checking \"$p_cmd\" ..."
 
-    $p_cmd -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);" || continue
-    $p_cmd -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);" || continue
+    "$p_cmd" -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);" || continue
+    "$p_cmd" -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);" || continue
 
-    ESP_PYTHON=$p_cmd
+    export ESP_PYTHON="$p_cmd"
     break
 done
+unset PYTHON_CANDIDATES
 
-$ESP_PYTHON --version 2>/dev/null || {
-    echo "Python ${OLDEST_PYTHON_SUPPORTED_MAJOR}.${OLDEST_PYTHON_SUPPORTED_MINOR}+ is not installed! Please see the documentation for how to install it."
+[[ -n "$ESP_PYTHON" ]] &&  "$ESP_PYTHON" --version 2>/dev/null || {
+    echo "Python ${OLDEST_PYTHON_SUPPORTED_MAJOR}.${OLDEST_PYTHON_SUPPORTED_MINOR}+ is not installed! Please see the documentation for how to install it." >&2
     exit 1
 }
 echo "\"$ESP_PYTHON\" has been detected"

From 0865ae64b2b3bc3ff527d7994ffb492698cd41cd Mon Sep 17 00:00:00 2001
From: garywill <garywill@disroot.org>
Date: Thu, 20 Nov 2025 12:03:00 +0800
Subject: [PATCH 2/8] Make detect_python.sh POSIX compatitable

---
 tools/detect_python.sh | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/tools/detect_python.sh b/tools/detect_python.sh
index 4290c5df19ee..a9e09615d06d 100644
--- a/tools/detect_python.sh
+++ b/tools/detect_python.sh
@@ -10,16 +10,20 @@
 OLDEST_PYTHON_SUPPORTED_MAJOR=3
 OLDEST_PYTHON_SUPPORTED_MINOR=10
 
+PYTHON_CANDIDATES="python3
+python
+python3.10
+python3.11
+python3.12
+python3.13"
 
-if [[ -z "$ESP_PYTHON" ]]; then
-    PYTHON_CANDIDATES=(python3 python python3.10 python3.11 python3.12 python3.13)
-else
+if [ -n "$ESP_PYTHON" ]; then
     echo "Reading ESP_PYTHON from environment: \"$ESP_PYTHON\""
-    PYTHON_CANDIDATES=("$ESP_PYTHON")
+    PYTHON_CANDIDATES="$ESP_PYTHON"
 fi
 ESP_PYTHON=  # Unset it. Will assign after candidate check
 
-for p_cmd in "${PYTHON_CANDIDATES[@]}"; do
+while IFS= read -r p_cmd; do
     "$p_cmd" --version >/dev/null 2>&1 || continue
     echo "Checking \"$p_cmd\" ..."
 
@@ -28,11 +32,14 @@ for p_cmd in "${PYTHON_CANDIDATES[@]}"; do
 
     export ESP_PYTHON="$p_cmd"
     break
-done
+done << EOF
+$PYTHON_CANDIDATES
+EOF
+
 unset PYTHON_CANDIDATES
 
-[[ -n "$ESP_PYTHON" ]] &&  "$ESP_PYTHON" --version 2>/dev/null || {
+if [ -z "$ESP_PYTHON" ]; then
     echo "Python ${OLDEST_PYTHON_SUPPORTED_MAJOR}.${OLDEST_PYTHON_SUPPORTED_MINOR}+ is not installed! Please see the documentation for how to install it." >&2
     exit 1
-}
+fi
 echo "\"$ESP_PYTHON\" has been detected"

From de48e9e91cefa5d3b0d82c437e2bcba559e7ec5c Mon Sep 17 00:00:00 2001
From: garywill <garywill@disroot.org>
Date: Thu, 20 Nov 2025 12:05:29 +0800
Subject: [PATCH 3/8] detect_python: Do not export ESP_PYTHON too early

---
 tools/detect_python.fish | 3 ++-
 tools/detect_python.sh   | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/tools/detect_python.fish b/tools/detect_python.fish
index 94afa02d59db..41c3239edf62 100644
--- a/tools/detect_python.fish
+++ b/tools/detect_python.fish
@@ -20,7 +20,7 @@ for p_cmd in $PYTHON_CANDIDATES
     $p_cmd -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);"; or continue
     $p_cmd -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);"; or continue
 
-    set -x ESP_PYTHON $p_cmd
+    set ESP_PYTHON $p_cmd
     break
 end
 set -e PYTHON_CANDIDATES
@@ -30,3 +30,4 @@ test -n "$ESP_PYTHON"; or exit 1
 
 $ESP_PYTHON --version
 echo "$ESP_PYTHON has been detected"
+set -x ESP_PYTHON $ESP_PYTHON
diff --git a/tools/detect_python.sh b/tools/detect_python.sh
index a9e09615d06d..29311d9b19cf 100644
--- a/tools/detect_python.sh
+++ b/tools/detect_python.sh
@@ -30,7 +30,7 @@ while IFS= read -r p_cmd; do
     "$p_cmd" -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);" || continue
     "$p_cmd" -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);" || continue
 
-    export ESP_PYTHON="$p_cmd"
+    ESP_PYTHON="$p_cmd"
     break
 done << EOF
 $PYTHON_CANDIDATES
@@ -43,3 +43,4 @@ if [ -z "$ESP_PYTHON" ]; then
     exit 1
 fi
 echo "\"$ESP_PYTHON\" has been detected"
+export ESP_PYTHON

From 9826934249d8718e795a082dd4dcfb7b9f4a2e59 Mon Sep 17 00:00:00 2001
From: garywill <garywill@disroot.org>
Date: Thu, 20 Nov 2025 12:10:20 +0800
Subject: [PATCH 4/8] Separate ESP_PYTHON and ESP_PYTHON_CUSTOM

Because if we 'unset ESP_PYTHON' in during python binary check,
it may break user's custom environment.
So we should separate those two variables
---
 docs/en/api-guides/tools/idf-tools.rst       | 2 +-
 docs/en/get-started/linux-macos-setup.rst    | 2 +-
 docs/zh_CN/api-guides/tools/idf-tools.rst    | 2 +-
 docs/zh_CN/get-started/linux-macos-setup.rst | 2 +-
 tools/detect_python.fish                     | 7 +++----
 tools/detect_python.sh                       | 9 ++++-----
 6 files changed, 11 insertions(+), 13 deletions(-)

diff --git a/docs/en/api-guides/tools/idf-tools.rst b/docs/en/api-guides/tools/idf-tools.rst
index f7041d20c3e0..10a2df360179 100644
--- a/docs/en/api-guides/tools/idf-tools.rst
+++ b/docs/en/api-guides/tools/idf-tools.rst
@@ -161,7 +161,7 @@ Shell-specific user-facing installation scripts are provided in the root directo
 * ``install.sh`` for Bash
 * ``install.fish`` for Fish
 
-Apart from downloading and installing the tools in ``IDF_TOOLS_PATH``, these scripts prepare a Python virtual environment, and install the required packages into that environment. If you want to specify a particular Python for ESP-IDF, you need to set environment variable ``ESP_PYTHON`` before installation and each time before use. For example ``export ESP_PYTHON=/opt/bin/python3.13``.
+Apart from downloading and installing the tools in ``IDF_TOOLS_PATH``, these scripts prepare a Python virtual environment, and install the required packages into that environment. If you want to specify a particular Python for ESP-IDF, you need to set environment variable ``ESP_PYTHON_CUSTOM`` before installation and each time before use. For example ``export ESP_PYTHON_CUSTOM=/opt/bin/python3.13``.
 
 These scripts accept optionally a comma-separated list of chip targets and ``--enable-*`` arguments for enabling features. These arguments are passed to the ``idf_tools.py`` script which stores them in ``idf-env.json``. Therefore, chip targets and features can be enabled incrementally.
 
diff --git a/docs/en/get-started/linux-macos-setup.rst b/docs/en/get-started/linux-macos-setup.rst
index 1d6b62cf4e55..f8022f54f431 100644
--- a/docs/en/get-started/linux-macos-setup.rst
+++ b/docs/en/get-started/linux-macos-setup.rst
@@ -116,7 +116,7 @@ To install supported Python 3 on macOS:
 
     During installation, the install script will check for supported Python versions on your system and select the oldest version that meets the minimum requirement.
 
-If you want to specify a particular Python for ESP-IDF, you need to set environment variable ``ESP_PYTHON`` before installation and each time before use. For example ``export ESP_PYTHON=/opt/bin/python3.13``.
+If you want to specify a particular Python for ESP-IDF, you need to set environment variable ``ESP_PYTHON_CUSTOM`` before installation and each time before use. For example ``export ESP_PYTHON_CUSTOM=/opt/bin/python3.13``.
     
 .. _get-started-get-esp-idf:
 
diff --git a/docs/zh_CN/api-guides/tools/idf-tools.rst b/docs/zh_CN/api-guides/tools/idf-tools.rst
index 2cee603fb69b..ea44ab103c36 100644
--- a/docs/zh_CN/api-guides/tools/idf-tools.rst
+++ b/docs/zh_CN/api-guides/tools/idf-tools.rst
@@ -161,7 +161,7 @@ ESP-IDF 的根目录中提供了针对不同 shell 的用户安装脚本，包
 * ``install.sh`` 适用于 Bash
 * ``install.fish`` 适用于 Fish
 
-这些脚本除了下载和安装 ``IDF_TOOLS_PATH`` 中的工具外，还会准备一个 Python 虚拟环境，并在此虚拟环境中安装所需软件包。如果要指定 ESP-IDF 使用特定的 Python ，则需要在安装之前及每次使用之前设置环境变量 ``ESP_PYTHON``，例如 ``export ESP_PYTHON=/opt/bin/python3.13``。
+这些脚本除了下载和安装 ``IDF_TOOLS_PATH`` 中的工具外，还会准备一个 Python 虚拟环境，并在此虚拟环境中安装所需软件包。如果要指定 ESP-IDF 使用特定的 Python ，则需要在安装之前及每次使用之前设置环境变量 ``ESP_PYTHON_CUSTOM``，例如 ``export ESP_PYTHON_CUSTOM=/opt/bin/python3.13``。
 
 为启用相应功能，这些脚本可以选择性地接受一组以逗号分隔的芯片目标列表及 ``--enable-*`` 参数，这类参数会传递给 ``idf_tools.py`` 脚本，并由该脚本将这类参数存储在 ``idf-env.json`` 中，从而逐步启用芯片目标及功能。
 
diff --git a/docs/zh_CN/get-started/linux-macos-setup.rst b/docs/zh_CN/get-started/linux-macos-setup.rst
index 759c337fcbab..17802aa5f903 100644
--- a/docs/zh_CN/get-started/linux-macos-setup.rst
+++ b/docs/zh_CN/get-started/linux-macos-setup.rst
@@ -116,7 +116,7 @@ Apple M1 用户
 
     安装过程中，安装脚本 (install.sh) 会检查系统中已安装的 Python 版本，并在所有符合最低要求的版本中，选择最早的版本使用。
     
-如果要指定 ESP-IDF 使用特定的 Python ，则需要在安装之前及每次使用之前设置环境变量 ``ESP_PYTHON``，例如 ``export ESP_PYTHON=/opt/bin/python3.13``。
+如果要指定 ESP-IDF 使用特定的 Python ，则需要在安装之前及每次使用之前设置环境变量 ``ESP_PYTHON_CUSTOM``，例如 ``export ESP_PYTHON_CUSTOM=/opt/bin/python3.13``。
 
 .. _get-started-get-esp-idf:
 
diff --git a/tools/detect_python.fish b/tools/detect_python.fish
index 41c3239edf62..163840ea2249 100644
--- a/tools/detect_python.fish
+++ b/tools/detect_python.fish
@@ -5,13 +5,12 @@
 set OLDEST_PYTHON_SUPPORTED_MAJOR 3
 set OLDEST_PYTHON_SUPPORTED_MINOR 10
 
-if test -z "$ESP_PYTHON"
+if test -z "$ESP_PYTHON_CUSTOM"
     set PYTHON_CANDIDATES python3 python python3.10 python3.11 python3.12 python3.13
 else
-    echo "Reading ESP_PYTHON from environment: \"$ESP_PYTHON\""
-    set PYTHON_CANDIDATES $ESP_PYTHON
+    echo "Reading ESP_PYTHON_CUSTOM from environment: \"$ESP_PYTHON_CUSTOM\""
+    set PYTHON_CANDIDATES $ESP_PYTHON_CUSTOM
 end
-set -e ESP_PYTHON  # Unset it. Will assign after candidate check
 
 for p_cmd in $PYTHON_CANDIDATES
     $p_cmd --version >/dev/null 2>&1; or continue
diff --git a/tools/detect_python.sh b/tools/detect_python.sh
index 29311d9b19cf..726272382c82 100644
--- a/tools/detect_python.sh
+++ b/tools/detect_python.sh
@@ -3,7 +3,7 @@
 # This is a helper script for detecting Python executables in the PATH. It is intended to be used for determining
 # which Python should be used with idf_tools.py for installing tools and exporting environment variables.
 #
-# 1. If environment variable ESP_PYTHON already set, script uses that python binary, otherwise, looks for python version same or greater than minimal required version on path
+# 1. If environment variable ESP_PYTHON_CUSTOM already set, script uses that python binary, otherwise, looks for python version same or greater than minimal required version on path
 # 2. If required version of python is found it is assigned to environmental variable `ESP_PYTHON`
 # 3. If required version of python is not found, script will fail
 
@@ -17,11 +17,10 @@ python3.11
 python3.12
 python3.13"
 
-if [ -n "$ESP_PYTHON" ]; then
-    echo "Reading ESP_PYTHON from environment: \"$ESP_PYTHON\""
-    PYTHON_CANDIDATES="$ESP_PYTHON"
+if [ -n "$ESP_PYTHON_CUSTOM" ]; then
+    echo "Reading ESP_PYTHON_CUSTOM from environment: \"$ESP_PYTHON_CUSTOM\""
+    PYTHON_CANDIDATES="$ESP_PYTHON_CUSTOM"
 fi
-ESP_PYTHON=  # Unset it. Will assign after candidate check
 
 while IFS= read -r p_cmd; do
     "$p_cmd" --version >/dev/null 2>&1 || continue

From c05b5bf5dfbf31e812c53a1b7f0bc2c05dbe4329 Mon Sep 17 00:00:00 2001
From: garywill <garywill@disroot.org>
Date: Thu, 20 Nov 2025 12:12:46 +0800
Subject: [PATCH 5/8] Fish shell: add quotes when setting variable value

---
 tools/detect_python.fish | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/tools/detect_python.fish b/tools/detect_python.fish
index 163840ea2249..6d97a221093b 100644
--- a/tools/detect_python.fish
+++ b/tools/detect_python.fish
@@ -9,7 +9,7 @@ if test -z "$ESP_PYTHON_CUSTOM"
     set PYTHON_CANDIDATES python3 python python3.10 python3.11 python3.12 python3.13
 else
     echo "Reading ESP_PYTHON_CUSTOM from environment: \"$ESP_PYTHON_CUSTOM\""
-    set PYTHON_CANDIDATES $ESP_PYTHON_CUSTOM
+    set PYTHON_CANDIDATES "$ESP_PYTHON_CUSTOM"
 end
 
 for p_cmd in $PYTHON_CANDIDATES
@@ -19,7 +19,7 @@ for p_cmd in $PYTHON_CANDIDATES
     $p_cmd -c "import sys; exit(1) if sys.version_info.major < int(\"$OLDEST_PYTHON_SUPPORTED_MAJOR\") else exit(0);"; or continue
     $p_cmd -c "import sys; exit(1) if sys.version_info.minor < int(\"$OLDEST_PYTHON_SUPPORTED_MINOR\") else exit(0);"; or continue
 
-    set ESP_PYTHON $p_cmd
+    set ESP_PYTHON "$p_cmd"
     break
 end
 set -e PYTHON_CANDIDATES
@@ -29,4 +29,4 @@ test -n "$ESP_PYTHON"; or exit 1
 
 $ESP_PYTHON --version
 echo "$ESP_PYTHON has been detected"
-set -x ESP_PYTHON $ESP_PYTHON
+set -x ESP_PYTHON "$ESP_PYTHON"

From 35764cbeeb391ad61e57557e44468ef1c2bd6c42 Mon Sep 17 00:00:00 2001
From: garywill <garywill@disroot.org>
Date: Thu, 20 Nov 2025 12:27:26 +0800
Subject: [PATCH 6/8] Fix: detect_python may kill user shell if no valid python

Using 'exit' may cause user shell killed if user runs '. export.sh'.
So use function to wrap the code.
---
 export.fish              | 2 +-
 export.sh                | 2 +-
 install.fish             | 2 +-
 install.sh               | 2 +-
 tools/detect_python.fish | 7 ++++++-
 tools/detect_python.sh   | 7 ++++++-
 6 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/export.fish b/export.fish
index 0187ca0fe54a..f86005079c07 100644
--- a/export.fish
+++ b/export.fish
@@ -16,7 +16,7 @@ if not test -f "$idf_path/tools/idf.py"
     exit 1
 end
 
-source "$idf_path"/tools/detect_python.fish
+source "$idf_path"/tools/detect_python.fish || return 1
 
 eval ("$ESP_PYTHON" "$idf_path"/tools/activate.py --export)
 set -e idf_path
diff --git a/export.sh b/export.sh
index 40bad17d3858..0f9f7e6b5f6c 100644
--- a/export.sh
+++ b/export.sh
@@ -53,7 +53,7 @@ then
     return 1
 fi
 
-. "${idf_path}/tools/detect_python.sh"
+. "${idf_path}/tools/detect_python.sh" || return 1
 
 # Evaluate the ESP-IDF environment set up by the activate.py script.
 idf_exports=$("$ESP_PYTHON" "${idf_path}/tools/activate.py" --export --shell $shell_type)
diff --git a/install.fish b/install.fish
index 065df8abe4d1..60da66bbf3f5 100755
--- a/install.fish
+++ b/install.fish
@@ -7,7 +7,7 @@ set -x IDF_PATH $basedir
 echo "INFO: Using IDF_PATH '$IDF_PATH' for installation."
 
 echo "Detecting the Python interpreter"
-source "$IDF_PATH"/tools/detect_python.fish
+source "$IDF_PATH"/tools/detect_python.fish || exit 1
 
 echo "Checking Python compatibility"
 "$ESP_PYTHON" "$IDF_PATH"/tools/python_version_checker.py
diff --git a/install.sh b/install.sh
index ce972c729019..e62b20233ab1 100755
--- a/install.sh
+++ b/install.sh
@@ -10,7 +10,7 @@ export IDF_PATH
 echo "INFO: Using IDF_PATH '${IDF_PATH}' for installation."
 
 echo "Detecting the Python interpreter"
-. "${IDF_PATH}/tools/detect_python.sh"
+. "${IDF_PATH}/tools/detect_python.sh" || exit 1
 
 echo "Checking Python compatibility"
 "${ESP_PYTHON}" "${IDF_PATH}/tools/python_version_checker.py"
diff --git a/tools/detect_python.fish b/tools/detect_python.fish
index 6d97a221093b..8c8f1d1b1c8e 100644
--- a/tools/detect_python.fish
+++ b/tools/detect_python.fish
@@ -2,6 +2,8 @@
 #
 # This is a port of detect_python.sh. More information are provided there.
 
+function detect_python
+
 set OLDEST_PYTHON_SUPPORTED_MAJOR 3
 set OLDEST_PYTHON_SUPPORTED_MINOR 10
 
@@ -25,8 +27,11 @@ end
 set -e PYTHON_CANDIDATES
 
 test -n "$ESP_PYTHON"; or echo "Python $OLDEST_PYTHON_SUPPORTED_MAJOR.$OLDEST_PYTHON_SUPPORTED_MINOR+ is not installed! Please see the documentation for how to install it." >&2
-test -n "$ESP_PYTHON"; or exit 1
+test -n "$ESP_PYTHON"; or return 1
 
 $ESP_PYTHON --version
 echo "$ESP_PYTHON has been detected"
 set -x ESP_PYTHON "$ESP_PYTHON"
+
+end
+detect_python
diff --git a/tools/detect_python.sh b/tools/detect_python.sh
index 726272382c82..747a5c2cb022 100644
--- a/tools/detect_python.sh
+++ b/tools/detect_python.sh
@@ -7,6 +7,8 @@
 # 2. If required version of python is found it is assigned to environmental variable `ESP_PYTHON`
 # 3. If required version of python is not found, script will fail
 
+detect_python () {
+
 OLDEST_PYTHON_SUPPORTED_MAJOR=3
 OLDEST_PYTHON_SUPPORTED_MINOR=10
 
@@ -39,7 +41,10 @@ unset PYTHON_CANDIDATES
 
 if [ -z "$ESP_PYTHON" ]; then
     echo "Python ${OLDEST_PYTHON_SUPPORTED_MAJOR}.${OLDEST_PYTHON_SUPPORTED_MINOR}+ is not installed! Please see the documentation for how to install it." >&2
-    exit 1
+    return 1
 fi
 echo "\"$ESP_PYTHON\" has been detected"
 export ESP_PYTHON
+
+}
+detect_python

From 6d70a272ac5227c52b1bdc84335682f4df726015 Mon Sep 17 00:00:00 2001
From: garywill <garywill@disroot.org>
Date: Thu, 20 Nov 2025 22:37:37 +0800
Subject: [PATCH 7/8] detect_python.sh comptitable with 'set -u', which
 install.sh set

---
 tools/detect_python.fish | 2 +-
 tools/detect_python.sh   | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/tools/detect_python.fish b/tools/detect_python.fish
index 8c8f1d1b1c8e..fe597aa1f20a 100644
--- a/tools/detect_python.fish
+++ b/tools/detect_python.fish
@@ -34,4 +34,4 @@ echo "$ESP_PYTHON has been detected"
 set -x ESP_PYTHON "$ESP_PYTHON"
 
 end
-detect_python
+detect_python # Make sure at last line call function, because outside caller need its return value
diff --git a/tools/detect_python.sh b/tools/detect_python.sh
index 747a5c2cb022..ff2ffa9ab91f 100644
--- a/tools/detect_python.sh
+++ b/tools/detect_python.sh
@@ -19,7 +19,7 @@ python3.11
 python3.12
 python3.13"
 
-if [ -n "$ESP_PYTHON_CUSTOM" ]; then
+if [ -n "${ESP_PYTHON_CUSTOM:-}" ]; then
     echo "Reading ESP_PYTHON_CUSTOM from environment: \"$ESP_PYTHON_CUSTOM\""
     PYTHON_CANDIDATES="$ESP_PYTHON_CUSTOM"
 fi
@@ -39,7 +39,7 @@ EOF
 
 unset PYTHON_CANDIDATES
 
-if [ -z "$ESP_PYTHON" ]; then
+if [ -z "${ESP_PYTHON:-}" ]; then
     echo "Python ${OLDEST_PYTHON_SUPPORTED_MAJOR}.${OLDEST_PYTHON_SUPPORTED_MINOR}+ is not installed! Please see the documentation for how to install it." >&2
     return 1
 fi
@@ -47,4 +47,4 @@ echo "\"$ESP_PYTHON\" has been detected"
 export ESP_PYTHON
 
 }
-detect_python
+detect_python # Make sure at last line call function, because outside caller need its return value

From 9d3eee7d7c0ae612e17f7a67f9244bcf701b4ad0 Mon Sep 17 00:00:00 2001
From: garywill <garywill@disroot.org>
Date: Thu, 20 Nov 2025 22:53:13 +0800
Subject: [PATCH 8/8] fix detect_python.fish: 'set -x' should be 'set -gx'
 because of function

---
 tools/detect_python.fish | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/detect_python.fish b/tools/detect_python.fish
index fe597aa1f20a..e01cfc7e159f 100644
--- a/tools/detect_python.fish
+++ b/tools/detect_python.fish
@@ -31,7 +31,7 @@ test -n "$ESP_PYTHON"; or return 1
 
 $ESP_PYTHON --version
 echo "$ESP_PYTHON has been detected"
-set -x ESP_PYTHON "$ESP_PYTHON"
+set -gx ESP_PYTHON "$ESP_PYTHON"
 
 end
 detect_python # Make sure at last line call function, because outside caller need its return value