03 python包管理工具——uv

官方文档：uv

一、安装与配置

1.1 安装

安装uv，提供了多种安装方式：

• 使用curl安装（macOS和Linux）：curl -LsSf https://astral.sh/uv/install.sh | sh
• 使用PowerShell安装（Windows）：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
• 使用pip安装：pip install uv

使用独立安装程序安装后，可以使用uv self update命令更新到最新版本。

1.2 Commands

uv run Run a command or script 运行命令或脚本

uv init Create a new project 创建新项目

uv add Add dependencies to the project 向项目添加依赖项

uv remove Remove dependencies from the project 从项目中删除依赖项

uv sync Update the project's environment 更新项目的环境

uv lock Update the project's lockfile 更新项目的锁文件

uv tree Display the project's dependency tree 显示项目的依赖树

uv venv Create a virtual environment 创建虚拟环境

uv tool Run and install commands provided by Python packages

运行和安装Python包提供的命令

uv python Manage Python versions and installations 管理Python版本和安装

uv pip Manage Python packages with a pip-compatible interface

使用pip兼容的接口管理Python包

uv export Export the project's lockfile to an alternate format 将项目的锁文件

导出为另一种格式

uv build Build Python packages into source distributions and wheels Python

打包到源代码发行版和轮子中

uv publish Upload distributions to an index 上传分布到索引

uv cache Manage uv's cache 管理uv的缓存

uv self Manage the uv executable 管理uv可执行文件

uv version Read or update the project's version 阅读或更新项目的版本

uv help Display documentation for a command 显示命令文档

二、核心功能

2.1 Python版本管理

uv可以轻松安装和管理多个Python版本，方便在不同版本的Python环境下进行开发和测试。

uv python list  # 查看uv支持的python版本

uv python install 3.10 3.11 3.12 # 安装指定版本的Python

uv python find 3.10  # 查找特定版本的python

uv python uninstall 3.10  # 卸载特定版本的python

uv run --python 3.12 python  # 指定版本运行python交互界面
uv run -p 3.12 python  # 指定版本运行python交互界面
uv run --python pypy@3.8 python
uv run -p pypy@3.8 python

uv python pin 3.11  # 在当前目录中使用特定的 Python 版本

2.2 项目管理

1.创建新项目

方式一：

uv init example
cd example

方式二：

mkdir test2
cd test2
uv init

2.创建虚拟环境

方式一：运行自动生成的main.py

uv run main.py

方式二：

uv venv
uv venv --python 3.11.6  # 指定python版本

3.环境文件说明

pyproject.toml

包含有关项目的元数据：pyproject.toml

[project]
name = "hello-world"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
dependencies = []

可以手动编辑此文件，然后执行uv sync 同步；也可以使用uv add 和 uv remove等命令从终端管理项目。

4.管理依赖项

uv add requests  # 添加依赖
uv add 'requests==2.31.0'  # 添加指定版本依赖
uv add -r requirements.txt  # 从文件添加依赖

uv remove requests  # 删除依赖

uv lock --upgrade-package requests # 升级软件包

uv tree  # 查看项目依赖树

5.运行

uv run可用于在项目环境中运行任意脚本或命令

uv run main.py

6.打包发布

# main.py
import argparse


def ma():
    parser = argparse.ArgumentParser(description="AI 脚本")
    parser.add_argument("arg1", type=str, help="第一个参数")
    parser.add_argument("arg2", type=int, help="第二个参数（整数）")
    args = parser.parse_args()
    print(f"参数1: {args.arg1}, 参数2: {args.arg2}")


if __name__ == "__main__":
    ma()

在pyproject.toml中增加[project.scripts]

ai为指定的可执行脚本，ai 映射到 main.ma 函数

[project]
name = "uv-test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

[project.scripts]
ai = "main:ma"

uv build  # 打包到源代码

# 安装刚才打包好的whl文件
uv tool install dist\uv_test-0.1.0-py3-none-any.whl

即可调用刚才设置的ai脚本，跟使用其他工具是一样的

2.3 工具管理

类似pipx，uv可以方便地安装和管理命令行工具。

uv tool install ruff  # 将ruff工具安装到系统环境中

uv tool uninstall ruff  # 卸载工具

which ruff  # 查看ruff安装路径

uv tool run ruff check
uvx ruff check  # uvx是uv tool run的别名,在临时环境中运行工具

uv tool list  # 查看已安装的工具

2.4 pip 接口

手动管理环境和包 - 旨在用于传统工作流或以下情况 高级命令没有提供足够的控制。

在环境中管理软件包（替换 pip 和 pipdeptree）：

uv pip install：将软件包安装到当前环境中。

uv pip show：显示有关已安装包的详细信息。

uv pip freeze：列出已安装的软件包及其版本。

uv pip check：检查当前环境是否有兼容的软件包。

uv pip list：列出已安装的软件包。

uv pip uninstall：卸载软件包。

uv pip tree：查看环境的依赖关系树。

2.5 公共管理

管理和检查 uv 的状态，例如缓存、存储目录，或执行 自我更新：

uv cache clean：删除缓存条目。

uv cache prune：删除过时的缓存条目。

uv cache dir：显示 uv 缓存目录路径。

uv tool dir：显示 uv 工具目录路径。

uv python dir：显示 uv 安装的 Python 版本路径。

uv self update：将 uv 更新到最新版本。