uv教程 虚拟环境

什么是uv

可以创建虚拟环境 安装依赖

安装uv

参见官方文档

安装 | uv-zh-cn

自定义安装目录,win+r 输入powershell，输入如下命令

$env:UV_INSTALL_DIR = "C:\Custom\Path";powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

将自定义的目录加入到path

可以执行uv，说明安装成功

如果被墙，那就从 https://github.com/astral-sh/uv/releases 下载压缩包

|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------|---------|
| uv-i686-pc-windows-msvc.zip | x86 Windows | 32位操作系统 |
| uv-x86_64-pc-windows-msvc.zip | x64 Windows | 64位操作系统 |

解压到存放目录，比如D:\uv，然后将目录D:\uv加入到系统环境变量path

系统环境变量操作见环境变量 - 白月黑羽

更新

uv self update 的行为

1. 检查当前安装位置

uv self update 会先确认自己是怎么被安装的。如果是通过 安装脚本 install.ps1 安装的，它会记住 $env:UV_INSTALL_DIR 的路径（因为脚本就是往那个路径里放了 uv.exe、uvx.exe、uvw.exe）。

2. 下载最新版本

它会去 astral-sh/uv 的 GitHub Releases 检查最新 release，并下载对应平台的压缩包（Windows 下是 .zip）。

3. 替换现有可执行文件

下载完成后，它会覆盖你安装目录里的旧文件：

C:\Custom\Path\uv.exe C:\Custom\Path\uvx.exe C:\Custom\Path\uvw.exe

如果你用 $env:UV_INSTALL_DIR 自定义了路径，那么 uv self update 会在那个目录里直接更新二进制文件，不会跑去默认目录

已有项目

uv的项目，后续新增库，等都用uv的命令操作。

完全uv

uv-zh-cn

Python包管理不再头疼：uv工具快速上手 - wang_yb - 博客园

UV使用教程 - 又一岁荣枯 - 博客园

假设 https://github.com/GiovanniGiacometti/python-repo-template/tree/main 这个是模板

Github配置ssh key的步骤（大白话+包含原理解释）_github生成ssh key-CSDN博客

1、pycharm中，解释器选成无解释器

2、进入项目根目录，执行 uv sync（命令行或者pycharm的终端都可以）, 此时会在项目的根目录建一个.env文件夹，把找到的python解释器放进去。uv sync = 统一入口，保证项目有对的python+venv+依赖，一键搞定。

uv sync会检查本地是否存在项目所需的python版本，若没有，自动去官方下载一个，保证环境可复现。

• 解析 Python 版本

  • 看 .python-version 或 pyproject.toml 里写的 Python 要求（比如 >=3.10,<3.13）。

  • 如果本地有符合的解释器 → 用本地的。

  • 如果本地没有 → 去下载对应的独立 Python（放到 uv python dir）。

• 创建虚拟环境

  • 在当前项目下生成 .venv/（除非你用 --no-venv）。

  • 把选中的 Python 解释器复制/链接进去。

• 安装依赖

  • 读取 pyproject.toml 或 requirements.txt 里的依赖。

  • 解析依赖 → 生成锁文件 uv.lock。

  • 把依赖安装到 .venv/。

uv 下载的python不是下载到了系统里，而是放在了它自己缓存/管理的目录中，避免和本地已有的python冲突。可以运行uv python list查看这里列出来的也可能是手动下载的，不是通过uv下载的，可以运行uv python dir查看uv下载的python。

自定义python存放路径

$env:UV_PYTHON_INSTALL_DIR = "D:\uv\python" uv sync

缓存

永久生效就设置到环境变量里，或者使用每个命令的时候加-- cache-dir。具体见uv文档的命令的章节

如果使用uv sync被拦截，则需要先下载对应的python版本。uv会根据i项目里的python版本，自动查找合适的python版本，去哪找的会显示

2.1 下载对应的python版本

首先输入 winget search python （Windows 包管理器 (winget) 搜索和 Python 相关的软件包）查找可以得到的python版本。

将ID列对应的python版本复制下，运行 winget install ID列python版本（Windows 包管理器 (winget) 来安装 Python x.x ），装好后，它会把 python.exe 和 pip.exe 放到系统路径（通常在 C:\Users\<你>\AppData\Local\Microsoft\WindowsApps），不支持选路径。

如果不想随便放，那就自己下载对应的版本放到某个位置，然后运行

uv sync --python "D:\Python313\python.exe"
告诉 uv：不要去自己找/下载 Python 版本，直接用我指定的这一只解释器来建环境。
uv 读取项目配置（.python-version 或 pyproject.toml → requires-python）

你用 --python 指定了解释器：

D:\Python313\python.exe


uv 会检查：

这只解释器是否存在；

它的版本号是否满足项目要求。

如果满足，就用它来：

创建 .venv/ 虚拟环境（.venv\Scripts\python.exe 会指向（复制或链接）你指定的 D:\Python313\python.exe。)

这样以后项目始终用这只解释器，而不会乱掉

安装依赖、生成/更新 uv.lock

3、pycharm,python解释器，选择虚拟环境中的python.exe

---

conda+uv

1、使用conda创建虚拟环境

2、进入i项目的根目录，执行uv sync -- python "conda虚拟环境里python的目录"

相当于不人工下载python，让conda下载python，conda管理自己下载的python。

卸载uv下载的python版本

新建项目

用 --python 参数

1、在初始化时就指定解释器路径或版本号：

本地要有 --python指定的解释器

uv init myproject --python "D:\Python313\python.exe" 结果：

• .python-version 会写成 3.13（对应你给的解释器）。

• pyproject.toml 的 [project] requires-python 也会是 >=3.13。

• 以后 uv sync 就会用这只解释器。

2、先uv init, 再改 .python-version

3、uv sync --python