Use system Python to install packages for embeddable Python

.github/workflows/build-windows-executable-app.yaml

@@ -235,18 +235,15 @@ jobs:
         cp $PYTHON_DIR/DLLs/tcl86t.dll $EMBED_DIR/
         cp $PYTHON_DIR/DLLs/tk86t.dll $EMBED_DIR/
 
-    - name: Install pip
-      run: |
-        curl -O https://bootstrap.pypa.io/get-pip.py
-        ./python-${{ env.PYTHON_VERSION }}/python get-pip.py --no-warn-script-location
-        rm get-pip.py
-
     - name: Uncomment 'import site' in python311._pth file
       run: |
         sed -i 's/#import site/import site/' python-${{ env.PYTHON_VERSION }}/python311._pth
 
     - name: Install Required Packages
-      run: .\python-${{ env.PYTHON_VERSION }}\python -m pip install --force-reinstall -r requirements.txt --no-warn-script-location
+      # Use system Python (which has development headers) to compile packages,
+      # installing into the embeddable Python's site-packages directory.
+      # The embeddable Python lacks Python.h headers needed for native extensions.
+      run: python -m pip install -r requirements.txt --target python-${{ env.PYTHON_VERSION }}/Lib/site-packages --upgrade --no-warn-script-location
 
     - name: Set to offline deployment
       run: |

.github/workflows/test-win-exe-w-embed-py.yaml

@@ -17,29 +17,31 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Set up Python (regular distribution)
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.PYTHON_VERSION }} # Use the same version as the embeddable version
+
       - name: Download python embeddable version
         run: |
           mkdir python-${{ env.PYTHON_VERSION }}
           curl -O https://www.python.org/ftp/python/${{ env.PYTHON_VERSION }}/python-${{ env.PYTHON_VERSION }}-embed-amd64.zip
           unzip python-${{ env.PYTHON_VERSION }}-embed-amd64.zip -d python-${{ env.PYTHON_VERSION }}
           rm python-${{ env.PYTHON_VERSION }}-embed-amd64.zip
 
-      - name: Install pip
-        run: |
-          curl -O https://bootstrap.pypa.io/get-pip.py
-          ./python-${{ env.PYTHON_VERSION }}/python get-pip.py --no-warn-script-location
-          rm get-pip.py
-
       - name: Uncomment 'import site' in python311._pth file
         run: |
           sed -i 's/#import site/import site/' python-${{ env.PYTHON_VERSION }}/python311._pth
-          
+
       - name: Print content of python311._pth file
         run: |
           cat python-${{ env.PYTHON_VERSION }}/python311._pth
 
       - name: Install Required Packages
-        run: .\python-${{ env.PYTHON_VERSION }}\python -m pip install -r requirements.txt --no-warn-script-location
+        # Use system Python (which has development headers) to compile packages,
+        # installing into the embeddable Python's site-packages directory.
+        # The embeddable Python lacks Python.h headers needed for native extensions.
+        run: python -m pip install -r requirements.txt --target python-${{ env.PYTHON_VERSION }}/Lib/site-packages --upgrade --no-warn-script-location
 
       - name: Create .bat file
         run: |

docs/win_exe_with_embed_py.md

@@ -3,6 +3,12 @@
 To create an executable for Streamlit app on Windows, we'll use an embeddable version of Python.</br>
 Here's a step-by-step guide:
 
+### Prerequisites
+
+You need a **system Python installation** (the regular Python installer from python.org) of the same version as the embeddable Python you'll download. This is required because the embeddable Python lacks development headers (`Python.h`) needed to compile native extensions.
+
+Install Python 3.11.9 from https://www.python.org/downloads/ if you don't have it already.
+
 ### Download and Extract Python Embeddable Version
 
 1. Download a suitable Python embeddable version. For example, let's download Python 3.11.9:
@@ -22,24 +28,6 @@ Here's a step-by-step guide:
    rm python-3.11.9-embed-amd64.zip
    ```
 
-### Install pip
-
-1. Download `get-pip.py`:
-
-   ```bash
-   # use curl command or manually download
-   curl -O https://bootstrap.pypa.io/get-pip.py
-   ```
-
-2. Install pip:
-
-   ```bash
-   ./python-3.11.9/python get-pip.py --no-warn-script-location
-
-   # no need anymore get-pip.py
-   rm get-pip.py
-   ```
-
 ### Configure Python Environment
 
 1. Uncomment 'import site' in the `._pth` file:
@@ -55,12 +43,20 @@ Here's a step-by-step guide:
 
 ### Install Required Packages
 
-Install all required packages from `requirements.txt`:
+Install all required packages from `requirements.txt` using the **system Python** with `--target` to install into the embeddable Python's site-packages:
 
 ```bash
-./python-3.11.9/python -m pip install -r requirements.txt --no-warn-script-location
+# Use system Python (which has development headers) to compile packages,
+# installing into the embeddable Python's site-packages directory.
+# The embeddable Python lacks Python.h headers needed for native extensions.
+python -m pip install -r requirements.txt --target python-3.11.9/Lib/site-packages --upgrade --no-warn-script-location
 ```
 
+> **Important**: Do NOT use `./python-3.11.9/python -m pip install ...` directly. The embeddable Python lacks the development headers required to compile native extensions (e.g., `Python.h`), which will cause builds to fail with errors like:
+> ```
+> fatal error C1083: Cannot open include file: 'Python.h': No such file or directory
+> ```
+
 ### Test and create `run_app.bat` file
 
 1. Test by running app