Python: docs(python/samples): recommend uv venv and document Windows ensurepip hang workaround - #5508
Merged
Evan Mattson (moonbox3) merged 5 commits intoMay 4, 2026
Conversation
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>
…s ensurepip hang workaround Fixes microsoft#5401
Evan Mattson (moonbox3)
added
documentation
Evan Mattson (moonbox3)
left a comment
Evan Mattson (moonbox3)
left a comment
Contributor
Author
There was a problem hiding this comment.
Automated Code Review
Reviewers: 4 | Confidence: 97% | Result: All clear
Reviewed: Correctness, Security Reliability, Test Coverage, Design Approach
Automated review by moonbox3's agents
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
Author
Python Test Coverage Report •
Python Unit Test Overview
|
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Python sample documentation to recommend uv venv as the primary virtual environment creation method, addressing a Windows/Microsoft Store Python ensurepip hang that can block initial setup for new users.
Changes:
- Update
azure_functionsandfoundry-hosted-agentssample READMEs to recommenduv venv .venvand document the Windowsensurepiphang workaround. - Minor formatting/cleanup tweaks in Python samples and core package (string formatting, extra blank lines, import removal,
__all__ordering).
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| python/samples/04-hosting/foundry-hosted-agents/README.md | Switches venv creation guidance to uv venv and adds note about Windows ensurepip hang. |
| python/samples/04-hosting/azure_functions/README.md | Switches venv creation guidance to uv venv and adds note about Windows ensurepip hang. |
| python/samples/04-hosting/a2a/agent_framework_to_a2a.py | Adds trailing comma in Agent(...) call for formatting consistency. |
| python/samples/01-get-started/06_functional_workflow_basics.py | Adds extra blank lines around snippet boundary. |
| python/samples/01-get-started/05_functional_workflow_with_agents.py | Adds extra blank lines around snippet boundary. |
| python/packages/core/tests/core/test_exceptions.py | Removes unused pytest import. |
| python/packages/core/agent_framework/init.py | Reorders AgentFrameworkException export within __all__. |
…s 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>
… `python -m venv` hangs on Windows — READMEs should recommend uv or document workaround
Evan Mattson (moonbox3)
left a comment
Evan Mattson (moonbox3)
left a comment
Contributor
Author
There was a problem hiding this comment.
Automated Code Review
Reviewers: 4 | Confidence: 100% | Result: All clear
Reviewed: Correctness, Security Reliability, Test Coverage, Design Approach
Automated review by moonbox3's agents
Tao Chen (TaoChenOSU)
approved these changes
Apr 27, 2026
# Conflicts: # python/samples/04-hosting/foundry-hosted-agents/README.md
Evan Mattson (moonbox3)
enabled auto-merge
May 4, 2026 02:40
Eduard van Valkenburg (eavanvalkenburg)
approved these changes
May 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation and Context
On Windows with Microsoft Store Python 3.13,
python -m venv .venvhangs indefinitely during theensurepipstep, blocking beginers at the very first setup instruction. Theazure_functionsandfoundry-hosted-agentssample READMEs both recommended this command with no guidance on alternatives.Fixes #5401
Description
The READMEs for
python/samples/04-hosting/azure_functionsandpython/samples/04-hosting/foundry-hosted-agentsare updated to replacepython -m venv .venvwithuv venv .venvas the primary (recommended) venv creation command, consistent with thea2asample which already useduv runexclusively. A note is added explaining thatpython -m venvstill works on other platforms but can hang on Windows/Microsoft Store Python due to a knownensurepipissue, directing users touv venvas the reliable alternative.Contribution Checklist