用uv管理python环境/项目(各种应用场景)

一、安装uv

有python的情况

pip install uv

Windows

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

linux或macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

二、换镜像源

uv不会读取pip的镜像源配置，所以要自己配置一下

2.1 针对项目换源

在项目文件的pyproject.toml中，添加如下内容：

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple/"

2.2 全局换源

Windows下换源

临时换源

powershell下执行

$env:UV_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"

永久换源

• 编辑[系统环境变量]，添加：
  • 变量名：UV_INDEX_URL
  • 变量值：https://pypi.tuna.tsinghua.edu.cn/simple

验证变量是否生效：

echo $env:UV_INDEX_URL

linux下换源

临时换源

export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

永久换源

echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.bashrc
source ~/.bashrc  # 立即生效

验证环境是否生效

echo $UV_INDEX_URL # 输出应为：https://pypi.tuna.tsinghua.edu.cn/simple

用法1：把uv当作pip加速的工具

把原来的pip命令前面加个uv，变成uv pip，提高包的安装速度

查看当前python包

uv pip list #查看当前python包
uv pip tree #查看当前python包，可显示包依赖关系

安装python包

uv pip install pandas #安装pandas包

卸载python包

uv pip uninstall pandas #卸载pandas包（不会卸载pandas依赖的包，这点与pip一样）

导出python包列表

uv pip freeze > requirements.txt

导入python包列表

uv pip install -r requirements.txt

用法2：创建新uv项目，运行

mkdir uvtest # 创建项目文件夹uvtest
cd uvtest # 进入项目文件夹
# uv init # 初始化项目，此时会在该文件夹中生成很多文件
uv init -p 3.12 #初始化项目时，指定python版本为3.12

打开.python-version，修改文件内容，切换项目python版本

执行python程序，测试环境

uv run main.py# 执行python程序
# 第一次执行uv run命令时，会将虚拟环境创建在.venv文件夹中
# 在vs code中选择该解释器路径：.\.venv\Scripts\python.exe

之后在项目文件夹中，通过终端执行uv命令管理python依赖

用法3：用uv的方式安装/卸载python包

查看当前python包

uv tree #查看当前python包，可显示包依赖关系

安装python包

uv add pandas #安装pandas包
# 执行该命令时，会自动修改pyproject.toml和uv.lock文件
uv add ruff --dev # ruff仅用于开发环境，不会被打包
# 注意：删除时也要加--dev: uv remove ruff --dev
uv add pytest --dev # 包仅用于开发环境，不会被打包
uv add mock --dev # 包仅用于开发环境，不会被打包

若使用uv pip install，则不会自动修改pyproject.toml和uv.lock文件，需要手动调用uv add，修改pyproject.toml和uv.lock文件
例：

uv pip install pandas # 安装了pandas包，但是没有修改pyproject.toml和uv.lock文件
uv add pandas # 手动修改pyproject.toml和uv.lock文件

卸载python包

uv remove pandas #卸载pandas包（会卸载pandas依赖的包，与pip不同）
# 执行该命令时，会自动修改pyproject.toml和uv.lock文件

升级python包

--upgrade-package表示将尝试将指定的包更新到最新的兼容版本，同时保持锁文件的其余部分不变。

uv lock --upgrade-package requests

导出python包列表

pyproject.toml和uv.lock文件中就是该项目的python依赖信息，已经被自动修改了，一般不需要手动导出

导入python包列表

uv sync # 根据pyproject.toml和uv.lock文件内容自动安装依赖包 

用法4：从已有环境创建新uv项目

现在将【老项目】（没用uv）中的python环境迁移到【新项目】（用了uv）中

进入【老项目】文件夹终端，执行如下命令，导出依赖列表

pip freeze > requirements.txt  # 调整绝对路径的模块

将requirements.txt文件移动至【新项目】文件夹中
打开【新项目】的.python-version文件，修改文件内容，输入与老项目相同的python版本
进入【新项目】文件夹终端，执行如下命令，导入依赖（顺便修改pyproject.toml和uv.lock文件）

uv add -r requirements.txt

此时可删除requirements.txt文件(因为环境已经导入进pyproject.toml和uv.lock了)

用法5：已有uv项目代码，创建该项目的环境

打开终端，进入项目文件夹，执行

uv sync  # 根据pyproject.toml和uv.lock文件内容自动安装依赖包

用法6：安装python工具，如ruff

ruff是个工具，本质上和项目代码无关，我们不希望在python环境中安装他。可以把ruff当作工具安装到系统环境中

uv tool uninstall ruff #安装ruff工具，这个ruff是脱离工程环境独立运行的
uv tool list # 当前已安装工具的列表

用法7：将python项目打包成whl文件，上传到python软件仓库

TODO：目前没需求，用到了再更新

uv build

参考

https://hellowac.github.io/uv-zh-cn/reference/