chakcy/virtualbox_client

Fork 0

Files

T

chakcy 9dec38db60 first commit

2026-05-10 10:56:52 +08:00

8.1 KiB

Raw Blame History

uv 使用文档

uv 是一个用 Rust 编写的极速 Python 包管理与工具链管理器，由 Astral 公司（Ruff 作者）开发。
它可替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等多个工具。

1. 简介

1.1 什么是 uv？

uv 是一个"大一统"的 Python 工具链，具备以下核心能力：

功能	对应传统工具
Python 版本安装与管理	pyenv
虚拟环境创建	venv / virtualenv
包安装	pip
依赖锁定	pip-tools / poetry
工具包运行	pipx
脚本依赖管理	原生支持

1.2 核心优势

极快速度：比 pip 快 10-100 倍
单一二进制：无需 Python 即可安装 uv
兼容性强：兼容 pip 的工作流和 requirements.txt
全面替代：一个工具解决 Python 环境所有问题

2. 安装与配置

2.1 一键安装（推荐）

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

安装后重启终端或执行：

source $HOME/.local/bin/env

2.2 其他安装方式

macOS (Homebrew):

brew install uv

Linux (apt/手动):

# 下载二进制
curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

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

2.3 验证安装

uv --version
# 输出示例: uv 0.11.11 (x86_64-unknown-linux-gnu)

2.4 配置国内镜像源（加速）

创建配置文件 ~/.config/uv/uv.toml：

# Python 版本下载镜像源
python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone/"

# pip 包下载镜像源（阿里云）
[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true

也可通过环境变量临时设置：

export UV_PYTHON_INSTALL_MIRROR="https://registry.npmmirror.com/-/binary/python-build-standalone/"

3. 核心命令速查

命令	说明
`uv python install <版本>`	安装指定 Python 版本
`uv python list`	列出可用的 Python 版本
`uv venv`	创建虚拟环境
`uv pip install <包>`	安装 Python 包
`uv pip sync requirements.txt`	同步依赖
`uv run <文件>`	在虚拟环境中运行脚本
`uv add <包>`	向项目添加依赖
`uv lock`	生成锁定文件
`uv tool run <工具>`	运行工具包（类似 pipx）
`uv init`	初始化新项目
`uv build`	构建分发包

4. Python 版本管理

4.1 查看可安装的 Python 版本

# 列出所有可下载的版本
uv python list --only-downloads

# 列出已安装的版本
uv python list

4.2 安装指定 Python 版本

# 安装最新 Python 3.12
uv python install 3.12

# 安装具体版本
uv python install 3.11.11

# 安装多个版本
uv python install 3.10 3.11 3.12

4.3 查看与切换当前 Python

# 查看当前使用的 Python
uv python

# 查找特定版本的路径
uv python find 3.11

# 为项目固定 Python 版本
uv python pin 3.12

4.4 卸载 Python 版本

# uv 安装的 Python 存储在 ~/.local/share/uv/python/
# 直接删除对应目录即可
rm -rf ~/.local/share/uv/python/cpython-3.10*

5. 虚拟环境管理

5.1 创建虚拟环境

# 在当前目录创建 .venv（使用默认 Python）
uv venv

# 指定 Python 版本创建
uv venv --python 3.12

# 指定名称
uv venv myenv

5.2 激活虚拟环境

# Linux / macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

提示：uv 会自动检测并使用当前目录下的 .venv，无需手动激活也可通过 uv run 使用。

5.3 删除虚拟环境

# 直接删除 .venv 目录即可
rm -rf .venv

6. 包管理

uv 兼容 pip 的全部功能，且速度更快。

6.1 安装包

# 安装单个包
uv pip install requests

# 安装指定版本
uv pip install "flask>=2.0"

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# 从 pyproject.toml 安装
uv pip install -e .

6.2 管理已安装的包

# 列出已安装的包
uv pip list

# 查看包信息
uv pip show requests

# 检查依赖冲突
uv pip check

# 卸载包
uv pip uninstall requests

6.3 依赖锁定

# 根据 requirements.in 编译出锁定文件
uv pip compile requirements.in -o requirements.txt

# 同步环境到锁定状态
uv pip sync requirements.txt

7. 项目工作流

7.1 初始化新项目

# 创建新项目
uv init my_project
cd my_project

# 添加依赖
uv add requests flask

# 安装所有依赖
uv sync

# 运行项目
uv run python main.py

7.2 脚本依赖管理（Shebang 方式）

在 Python 脚本顶部添加内联元数据，自动管理依赖：

# /// script
# dependencies = [
#   "requests>=2.28",
#   "rich>=13.0",
# ]
# ///
import requests
from rich import print

response = requests.get("https://api.github.com")
print(response.status_code)

运行方式：

uv run script.py

uv 会自动创建隔离环境并安装依赖，无需手动管理！

7.3 工具包管理（替代 pipx）

# 安装工具包
uv tool install ruff

# 运行工具（无需安装）
uv tool run black --help

# 列出已安装的工具
uv tool list

# 升级工具
uv tool upgrade ruff

# 卸载工具
uv tool uninstall ruff

8. 镜像源配置

8.1 配置文件方式

编辑 ~/.config/uv/uv.toml：

# ========== Python 版本下载镜像 ==========
python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone/"

# ========== 包下载镜像源 ==========
[[index]]
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true

# 可配置多个备用镜像源
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"

8.2 环境变量方式

# Python 版本下载镜像
export UV_PYTHON_INSTALL_MIRROR="https://registry.npmmirror.com/-/binary/python-build-standalone/"

# 包下载镜像（临时覆盖）
export UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"

8.3 常用国内镜像源

镜像源	Python 版本镜像 URL	PyPI 镜像 URL
华为云	`https://repo.huaweicloud.com/python`	`https://mirrors.huaweicloud.com/repository/pypi/simple`
阿里云	-	`https://mirrors.aliyun.com/pypi/simple/`
清华大学	`https://mirrors.tuna.tsinghua.edu.cn/python`	`https://pypi.tuna.tsinghua.edu.cn/simple/`
中科大	`https://mirrors.ustc.edu.cn/python`	`https://pypi.mirrors.ustc.edu.cn/simple/`

9. 常见问题

Q1: 安装时遇到权限问题？

# 确保 ~/.local/bin 在 PATH 中
export PATH="$HOME/.local/bin:$PATH"

Q2: 如何更新 uv？

uv self update

Q3: uv 和 pip 能否共存？

完全可以。uv 兼容 pip 的工作流，两者可共存使用。建议逐步迁移到 uv。

Q4: 如何查看帮助？

# 通用帮助
uv help

# 子命令帮助
uv python --help
uv pip --help

Q5: 如何卸载 uv？

# 删除二进制文件
rm ~/.local/bin/uv ~/.local/bin/uvx

# 删除配置
rm -rf ~/.config/uv

# 删除缓存
rm -rf ~/.cache/uv

# 删除安装的 Python 版本
rm -rf ~/.local/share/uv

Q6: 为什么我执行 `uv python install` 下载很慢？

请检查是否已配置国内镜像源（参见第 8 节），或手动设置：

export UV_PYTHON_INSTALL_MIRROR="https://registry.npmmirror.com/-/binary/python-build-standalone/"

8.1 KiB Raw Blame History Unescape Escape