Python: docs(python/samples): recommend uv venv and document Windows ensurepip hang workaround (microsoft#5508)

moonbox3 · Copilot · Copilot · web-flow · commit 6582926af591 · 2026-05-04T04:46:17.000Z
* docs(samples): recommend uv venv to avoid Windows ensurepip hang Replace bare 'python -m venv .venv' with 'uv venv .venv' as the recommended approach in azure_functions and foundry-hosted-agents READMEs. Add a note explaining that python -m venv can hang indefinitely on Windows with Microsoft Store Python due to a known ensurepip issue. This matches the pattern already used in a2a/README.md which uses uv run exclusively. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Python: docs(python/samples): recommend `uv venv` and document Windows ensurepip hang workaround Fixes microsoft#5401 * fix: correct Windows venv activation commands in foundry-hosted-agents README (microsoft#5401) Split the Windows activation section into separate PowerShell (.venv\Scripts\Activate.ps1) and Command Prompt (.venv\Scripts\activate.bat) instructions, replacing the incorrect extensionless `Activate` path. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address review feedback for microsoft#5401: Python: [Samples][Python] `python -m venv` hangs on Windows — READMEs should recommend uv or document workaround --------- Co-authored-by: Copilot <copilot@github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
diff --git a/python/samples/04-hosting/azure_functions/README.md b/python/samples/04-hosting/azure_functions/README.md
@@ -19,18 +19,22 @@ All of these samples are set up to run in Azure Functions. Azure Functions has a
 
 ### 2. Create and activate a virtual environment
 
+Using [uv](https://docs.astral.sh/uv/) (recommended):
+
 **Windows (PowerShell):**
 ```powershell
-python -m venv .venv
+uv venv .venv
 .venv\Scripts\Activate.ps1
 ```
 
 **Linux/macOS:**
 ```bash
-python -m venv .venv
+uv venv .venv
 source .venv/bin/activate
 ```
 
+> **Note:** `python -m venv .venv` also works, but can hang indefinitely on Windows with Microsoft Store Python due to a known `ensurepip` issue. Use `uv venv .venv` to avoid this.
+
 ### 3. Running the samples
 
 - [Start the Azurite emulator](https://learn.microsoft.com/en-us/azure/storage/common/storage-install-azurite?tabs=npm%2Cblob-storage#run-azurite)
diff --git a/python/samples/04-hosting/foundry-hosted-agents/README.md b/python/samples/04-hosting/foundry-hosted-agents/README.md
@@ -134,18 +134,25 @@ cd agent-framework/python/samples/04-hosting/foundry-hosted-agents/responses
 
 #### Environment setup
 
-1. Navigate to the sample directory you want to explore. Create a virtual environment:
+1. Navigate to the sample directory you want to explore. Create and activate a virtual environment using [uv](https://docs.astral.sh/uv/) (recommended):
 
    ```bash
-   python -m venv .venv
+   uv venv .venv
+   ```
+
+   ```bash
+   # Windows (PowerShell)
+   .venv\Scripts\Activate.ps1
 
-   # Windows
-   .venv\Scripts\Activate
+   # Windows (Command Prompt)
+   .venv\Scripts\activate.bat
 
    # macOS/Linux
    source .venv/bin/activate
    ```
 
+   > **Note:** `python -m venv .venv` also works, but can hang indefinitely on Windows with Microsoft Store Python due to a known `ensurepip` issue. Use `uv venv .venv` to avoid this.
+
 2. Install dependencies:
 
    ```bash
