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

* 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 <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Evan Mattson
2026-05-04 13:46:17 +09:00
committed by GitHub
Unverified
parent 0507179d3b
commit 6582926af5
2 changed files with 17 additions and 6 deletions
@@ -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)
@@ -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