Windows Python Install Manager 和 uv 使用速查

本文记录时间：2026-07-07。命令以 Windows PowerShell 为主。

1. 它们分别是什么

Windows Python Install Manager

Python Install Manager，常见命令为 py / pymanager，是 CPython 官方在 Windows 上推荐的 Python 安装和运行时管理工具。它负责：

• 安装和更新 Python 运行时，例如 CPython 3.14、3.13、3.12。
• 提供全局命令：python、py、pymanager。
• 在多版本 Python 共存时选择默认版本或指定版本。
• 管理由它安装的 Python 运行时，包括列出、更新、卸载、离线安装。

简单理解：它主要管“Windows 上装哪些 Python 解释器，以及运行哪个解释器”。

uv

uv 是 Astral 开发的 Python 包和项目管理工具，使用 Rust 编写。它可以替代或覆盖很多常见工具的使用场景，例如 pip、pip-tools、pipx、poetry、virtualenv、部分 pyenv 工作流等。它负责：

• 创建和管理 Python 项目。
• 安装、移除、锁定和同步依赖。
• 创建虚拟环境。
• 运行脚本和项目命令。
• 安装并运行 Python 命令行工具，例如 ruff、black、pytest。
• 可选地安装和管理 Python 版本。
• 提供兼容 pip 的 uv pip ... 命令。

简单理解：它主要管“项目、依赖、虚拟环境和工具”，也可以管理 Python 版本。

2. 关系和选择建议

两者不是完全替代关系。

• 如果只想在 Windows 上安装官方 CPython，并让 python / py 命令可用，优先使用 Python Install Manager。
• 如果在做项目开发，需要更快地安装依赖、创建虚拟环境、锁定依赖、运行工具，优先使用 uv。
• 可以同时使用：用 Python Install Manager 安装系统级 Python，用 uv 管理项目依赖和虚拟环境。
• 如果希望跨平台统一 Python 版本、项目和依赖管理，也可以主要使用 uv。

推荐日常组合：

# Windows 上安装 Python
py install 3.14

# 项目内使用 uv
uv init
uv add requests
uv run python main.py

3. 安装 Python Install Manager

方法一：Microsoft Store

在 Microsoft Store 中安装 Python Install Manager。安装完成后打开 PowerShell：

python
py
pymanager

方法二：python.org 下载

从 Python 官网下载 Python Install Manager 安装包。下载后可以双击安装，也可以在 PowerShell 中运行：

Add-AppxPackage <path-to-msix>

方法三：WinGet 自动安装

适合脚本化安装：

winget install 9NQ7512CXL7T -e --accept-package-agreements --disable-interactivity

安装后可运行配置检查：

py install --configure -y

安装后检查

python --version
py --version
pymanager --version
py list

如果 python 或 py 找不到，检查：

• Windows “管理应用执行别名” 中 Python 相关别名是否启用。
• PATH 是否包含 %UserProfile%\AppData\Local\Microsoft\WindowsApps。
• 是否存在旧版 Python Launcher 抢占了 py 命令。

4. Python Install Manager 常用命令

查看帮助

py help
py help install
py install /?

运行 Python

python
py
python script.py
py -m pip --version

指定 Python 版本运行

py -V:3.14
py -V:3.14 script.py
py -V:3.13 -m pip --version

兼容旧版 launcher 的简写在官方 CPython 版本上通常也可用：

py -3.14

列出已安装 Python

py list
py list --only-managed
py list --format=json
py list --one 3.14

查询可在线安装的 Python

py list --online
py list --online 3.14
py list --online --one 3.14

安装 Python 运行时

py install
py install 3.14
py install 3.13 3.12
py install default

更新 Python 运行时

py install --update
py install --update 3.14

注意：更新运行时可能会移除该运行时里的全局安装包；项目虚拟环境通常不受影响。

重新生成全局快捷命令

安装某些包后，如果命令行工具找不到，可以刷新入口：

py install --refresh

预演安装，不实际修改

py install --dry-run 3.14

卸载 Python 运行时

py uninstall 3.13
py uninstall -y 3.13

清理由 Python Install Manager 管理的所有运行时：

py uninstall --purge

离线安装

在有网络的机器上下载离线索引：

py install --download=C:\python-offline 3.14

拷贝目录到离线机器后安装：

py install --source="C:\python-offline\index.json" 3.14

5. 安装 uv

方法一：官方 standalone 安装脚本

PowerShell：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

指定 uv 版本：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.11.27/install.ps1 | iex"

安装前查看脚本内容：

powershell -c "irm https://astral.sh/uv/install.ps1 | more"

方法二：WinGet

winget install --id=astral-sh.uv -e

方法三：Scoop

scoop install main/uv

方法四：pipx

pipx install uv

方法五：pip

pip install uv

如果使用 pip 安装，建议优先安装到隔离环境，而不是混进某个项目环境。

安装后检查

uv --version
uv help

更新 uv

如果通过 standalone 安装脚本安装：

uv self update

如果通过包管理器安装，用对应包管理器升级，例如：

winget upgrade --id=astral-sh.uv -e
scoop update main/uv
pip install --upgrade uv
pipx upgrade uv

6. uv 常用命令

创建项目

uv init
uv init my-project
cd my-project

常见文件：

• pyproject.toml：项目元数据和依赖声明。
• uv.lock：锁定解析后的依赖版本。
• .venv：项目虚拟环境，通常由 uv 自动创建。

添加依赖

uv add requests
uv add "django>=5"
uv add pytest --dev

移除依赖

uv remove requests
uv remove pytest --dev

安装/同步项目依赖

uv sync

只同步生产依赖：

uv sync --no-dev

运行命令

uv run python --version
uv run python main.py
uv run pytest
uv run ruff check

uv run 会在项目环境中运行命令，必要时创建或更新 .venv。

锁定依赖

uv lock

查看依赖树：

uv tree

创建虚拟环境

uv venv
uv venv .venv
uv venv --python 3.14

激活虚拟环境：

.\.venv\Scripts\Activate.ps1

退出虚拟环境：

deactivate

使用 pip 兼容接口

创建环境：

uv venv

安装包：

uv pip install requests
uv pip install -r requirements.txt

列出包：

uv pip list
uv pip freeze

卸载包：

uv pip uninstall requests

同步 requirements：

uv pip sync requirements.txt

编译 requirements：

uv pip compile requirements.in -o requirements.txt

安装和运行命令行工具

临时运行工具，不长期安装：

uvx ruff check .
uv tool run black --version

安装用户级工具：

uv tool install ruff
uv tool install black

查看已安装工具：

uv tool list

卸载工具：

uv tool uninstall ruff

更新 shell，使工具命令进入 PATH：

uv tool update-shell

管理 Python 版本

列出可用 Python：

uv python list

安装 Python：

uv python install 3.14
uv python install 3.13 3.12

查找 Python：

uv python find
uv python find 3.14

为当前目录固定 Python 版本：

uv python pin 3.14

卸载 uv 管理的 Python：

uv python uninstall 3.13

单文件脚本依赖

给脚本添加内联依赖元数据：

uv add --script example.py requests

运行脚本：

uv run example.py

移除脚本依赖：

uv remove --script example.py requests

7. 常见工作流

新项目

uv init demo
cd demo
uv add requests
uv add pytest --dev
uv run python -c "import requests; print(requests.__version__)"
uv run pytest

已有 requirements.txt 项目

uv venv
uv pip install -r requirements.txt
uv run python app.py

或者严格同步：

uv pip sync requirements.txt

已有 pyproject.toml 项目

uv sync
uv run python main.py

使用指定 Python 版本开发

uv python install 3.14
uv python pin 3.14
uv sync
uv run python --version

用 PIM 安装 Python，用 uv 管项目

py install 3.14
uv init demo
cd demo
uv venv --python 3.14
uv add requests
uv run python main.py

8. 常见问题

python 打开 Microsoft Store 或提示找不到

检查 Python Install Manager 是否已安装。再检查 Windows “管理应用执行别名”，确保 Python 相关别名启用。还要检查 PATH 是否包含：

%UserProfile%\AppData\Local\Microsoft\WindowsApps

py 不是 Python Install Manager

可能是旧版 Python Launcher 抢占。可尝试：

pymanager help
pymanager list

如果确认旧 launcher 干扰，可在 Windows “已安装的应用” 中卸载旧的 Python Launcher，或在脚本中明确使用 pymanager。

pip 安装了工具但命令找不到

如果是 Python Install Manager 管理的 Python，可刷新全局入口：

py install --refresh

如果是在 uv 项目里，优先用：

uv run <command>

如果是 uv 用户级工具，运行：

uv tool update-shell

uv 命令找不到

重启 PowerShell，或者确认 uv 的安装目录已加入 PATH。如果使用 standalone 安装脚本，通常安装器会尝试修改 shell 配置。

要不要手动激活 .venv

使用 uv 时很多场景不需要手动激活，直接：

uv run python main.py
uv run pytest

如果你想在当前 shell 中直接运行 python、pip 或工具命令，可以激活：

.\.venv\Scripts\Activate.ps1

9. 一句话总结

• Python Install Manager：Windows 上官方 Python 解释器安装器和多版本管理器。
• uv：高速 Python 项目、依赖、虚拟环境、工具和 Python 版本管理器。
• 日常开发推荐：PIM 保证 Windows 上有 Python，uv 管每个项目。

10. 官方资料

• Python on Windows / Python Install Manager: https://docs.python.org/3/using/windows.html
• uv 官方文档: https://docs.astral.sh/uv/
• uv 安装文档: https://docs.astral.sh/uv/getting-started/installation/
• uv 功能概览: https://docs.astral.sh/uv/getting-started/features/