Python项目环境管理工具：uv
Table of Contents
uv 是一个方便高效的 Python 包和项目管理工具，用 Rust 编写。类似于 npm 和 cargo 等工具.可以代替 pip、pip-tools、pipx、poetry、pyenv、twine、virtualenv 等工具，用于管理项目中的依赖包和虚拟环境。并且由于原理不同，uv 下载导入包的速度比 pip 快 10 到 100 倍。
安装
Windows：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
macOS 和 Linux：
curl -LsSf https://astral.sh/uv/install.sh | sh
卸载
清除存储的数据（可选）
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"
删除 uv 二进制文件
Windows：
rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
macOS 和 Linux：
rm ~/.local/bin/uv ~/.local/bin/uvx
使用
安装后，可以在命令行中输入 uv 来检验是否安装成功。
python 版本管理
uv python install 3.11 3.12 # 安装指定版本的python（可多个）
uv python list # 查看可安装的 python 版本
uv python find # 查找已安装的 Python 版本
uv python pin # 将当前项目锁定为使用特定的 Python 版本
uv python uninstall # 卸载 Python 版本
uv python install pypy@3.10 # 安装pypy版本的python
管理单个脚本（不常用）
创建单个 python 脚本：
uv init --script example.py --python 3.12 # 指定脚本名称和python版本
运行无外部依赖包的脚本：
uv run example.py # 运行没有外部依赖包的脚本
uv run --no-project example.py # 不使用 pyproject.toml 中的依赖
uv run --python 3.10 example.py # 使用指定版本 python 运行脚本
运行有外部依赖包的脚本：
uv run --with rich example.py # 运行脚本时，使用 rich 依赖包
--with可以使用多次，用于请求多个依赖包。
除了在运行时指定依赖包，也可以提前声明脚本依赖：
uv add --script example.py 'requests<3' 'rich'
这会在脚本顶部添加一个 script 部分的注释，使用 toml 格式声明。
# /// script
# dependencies = [
# "requests<3",
# "rich",
# ]
# ///
import requests
from rich.pretty import pprint
resp = requests.get("https://peps.python.org/api/peps.json")
data = resp.json()
pprint([(k, v["title"]) for k, v in data.items()][:10])
uv remove --script example.py 'rich' # 从脚本中移除依赖
这种依赖管理方式，对于单个脚本来说比较繁琐，因此不常用。uv 还是多用于管理整个 python 项目。
管理整个项目（常用）
uv 管理一个 python 项目，依靠的是项目中的 pyproject.toml 文件，其中保存着项目的所有配置信息，uv 会自动维护它。
uv init # 创建一个 python 项目
uv add # 添加一个依赖项到项目中
uv remove # 从项目中移除一个依赖项
uv sync # 同步项目的依赖项与环境
uv lock # 为项目的依赖项创建一个锁定文件
uv run # 在项目环境中运行一个命令
uv tree # 查看项目的依赖树
uv build # 将项目构建为分发存档
uv publish # 将项目发布到包索引
创建一个 python 项目：
uv init hello-world # 创建一个hello-world文件夹并初始化
# 等同于
mkdir hello-world
cd hello-world
uv init
也可以通过 --python 3.14 来指定 python 版本。
uv 会创建以下文件：
.
├── .git
├── .python-version
├── README.md
├── main.py
└── pyproject.toml
首次运行项目命令（如 uv.lock、uv run、uv sync 或 uv lock）时，uv 还会在项目根目录下创建一个虚拟环境（.venv）和一个 uv.lock 文件。
pyproject.toml包含关于你的项目的元数据.python-version包含项目的默认 Python 版本.venv文件夹包含您的项目的虚拟环境uv.lock是一个跨平台的锁定文件，包含关于项目依赖项的精确信息（本质是 TOML 文件）
添加一个依赖到项目中：
uv add requests # 添加 requests 依赖
uv add 'requests==2.31.0' # 指定 requests 的版本
uv add git+https://github.com/psf/requests # 指定依赖的来源地址
uv add -r requirements.txt -c constraints.txt # 从 requirements.txt 迁移依赖
从项目中移除一个依赖：
uv remove requests # 移除 requests 依赖
要升级一个包，运行 uv lock 并带上 --upgrade-package 标志：
uv lock --upgrade-package requests
运行项目：
uv run main.py # 运行脚本
uv add flask
uv run -- flask run -p 3000 # 运行项目命令
在每次调用 uv run 之前，uv 都会验证锁文件与 pyproject.toml 一致，并且环境与锁文件一致，从而无需手动干预即可保持项目同步。 uv run 确保您的命令在一致且锁定的环境中运行。
或者，也可以使用 uv sync 手动更新环境，然后激活它再执行命令：
uv sync
.venv\Scripts\activate
flask run -p 3000
python example.py
构建分发包：
uv build 可用于构建项目的源分发包和二进制分发包（wheel）。
默认情况下， uv build 将在当前目录构建项目，并将构建产物放在一个名为 dist/ 的子目录中：
uv build
ls dist/
hello-world-0.1.0-py3-none-any.whl
hello-world-0.1.0.tar.gz
使用命令行工具
python 中有许多工具，如用于测试的 pytest，用于检查格式的 ruff，都是命令行工具的形式，不需要在前面使用 python。这些工具同样也可以直接在 uv 中管理和使用。
uv tool run # 在临时环境中运行工具
uvx == uv tool run # uvx 是 uv tool run 的别名
使用
uvx时，工具会安装到临时且隔离的环境中。
uv tool install # 在用户范围内安装一个工具
uv tool uninstall # 卸载一个工具
uv tool list # 列出已安装的工具
uv tool update-shell # 更新 shell 以包含工具可执行文件
例如：
uv tool install pytest
uv tool run pytest
uv tool unistall pytest
pip 接口
uv 也可以直接使用 pip 的命令接口，用于手动管理环境和包。
uv venv # 创建一个新的虚拟环境
uv pip install # 将包安装到当前环境
uv pip show # 显示已安装包的详细信息
uv pip freeze # 列出已安装的包及其版本
uv pip check # 检查当前环境是否包含兼容的包
uv pip list # 列出已安装的包
uv pip uninstall # 卸载软件包
uv pip tree # 查看环境的依赖树