From 6582926af591cb2bac43dfe4f1b3619323246697 Mon Sep 17 00:00:00 2001 From: Evan Mattson <35585003+moonbox3@users.noreply.github.com> Date: Mon, 4 May 2026 13:46:17 +0900 Subject: [PATCH] Python: docs(python/samples): recommend `uv venv` and document Windows ensurepip hang workaround (#5508) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 #5401 * fix: correct Windows venv activation commands in foundry-hosted-agents README (#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 #5401: Python: [Samples][Python] `python -m venv` hangs on Windows — READMEs should recommend uv or document workaround --------- Co-authored-by: Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../samples/04-hosting/azure_functions/README.md | 8 ++++++-- .../04-hosting/foundry-hosted-agents/README.md | 15 +++++++++++---- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/python/samples/04-hosting/azure_functions/README.md b/python/samples/04-hosting/azure_functions/README.md index cd410771c6..0580dee843 100644 --- 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 index dfecb1531b..0ff8c9e945 100644 --- 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 + ``` - # Windows - .venv\Scripts\Activate + ```bash + # Windows (PowerShell) + .venv\Scripts\Activate.ps1 + + # 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