python uv常用命令使用及说明

什么是 UV？

UV 是一个快速的 Python 包安装器和解析器，是 pip 和 pip-tools 的现代替代品，用 Rust 编写，速度极快。

安装 UV

# 使用 pip 安装
pip install uv

# 使用安装脚本（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 在 Windows 上（使用 PowerShell）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

基本命令

1. 初始化项目

# 在当前目录初始化 Python 项目
uv init

# 指定项目名称
uv init my-project

2. 管理虚拟环境

# 创建虚拟环境（默认在 .venv 目录）
uv venv

# 指定虚拟环境名称
uv venv myenv

# 使用特定 Python 版本
uv venv --python 3.11

# 激活虚拟环境
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate

# 删除虚拟环境
uv venv --remove

3. 包管理

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

# 安装单个包
uv pip install requests

# 安装指定版本
uv pip install "requests==2.31.0"

# 安装开发依赖
uv pip install -e ".[dev]"

# 安装 extras
uv pip install "package[extra1,extra2]"

# 生成 requirements.txt（包含所有依赖）
uv pip compile pyproject.toml -o requirements.txt

# 仅生成直接依赖
uv pip compile pyproject.toml --no-dev -o requirements.txt

# 生成带有哈希值的锁定文件
uv pip compile pyproject.toml --generate-hashes

# 升级所有包
uv pip install --upgrade -r requirements.txt

# 升级特定包
uv pip install --upgrade requests

uv pip uninstall package_name

4. 项目管理

# 同步虚拟环境与 requirements.txt
uv pip sync requirements.txt

# 同步并升级
uv pip sync --upgrade requirements.txt

# 列出所有已安装包
uv pip list

# 显示过时的包
uv pip list --outdated

# 显示依赖树
uv pip show package_name

5. 运行 Python 脚本

# 运行 Python 脚本
uv run python script.py

# 运行模块
uv run -m module_name

# 运行并传递参数
uv run python script.py arg1 arg2

6. 锁文件管理

# 生成锁文件
uv lock

# 从锁文件同步
uv sync

# 更新锁文件
uv lock --upgrade

高级用法

配置 UV

# 设置全局 Python 版本
uv python pin 3.11

# 设置镜像源
uv config set install.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 设置缓存目录
uv config set cache-dir /path/to/cache

性能优化

# 并行安装（默认启用）
uv pip install --parallel

# 禁用缓存
uv pip install --no-cache

# 清除缓存
uv cache clean

项目结构示例

my-project/
├── pyproject.toml    # 项目配置和依赖声明
├── uv.lock           # 锁文件（自动生成）
├── requirements.txt  # 依赖文件
├── .venv/           # 虚拟环境
└── src/
    └── app.py

pyproject.toml 示例

[project]
name = "my-project"
version = "0.1.0"
dependencies = [
    "requests>=2.28.0",
    "click>=8.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
]
test = [
    "pytest>=7.0.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

常用工作流

1. 新项目初始化

# 1. 创建项目
uv init myproject
cd myproject

# 2. 创建虚拟环境
uv venv

# 3. 激活环境
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate    # Windows

# 4. 添加依赖
uv pip install requests pandas

# 5. 生成 requirements.txt
uv pip freeze > requirements.txt

2. 现有项目设置

# 1. 克隆项目
git clone project-url
cd project

# 2. 创建虚拟环境
uv venv

# 3. 安装依赖
uv pip install -r requirements.txt

# 4. 运行项目
uv run python main.py

3. 依赖更新工作流

# 1. 检查过时的包
uv pip list --outdated

# 2. 更新 requirements.txt
uv pip install --upgrade package_name

# 3. 生成新的 requirements.txt
uv pip freeze > requirements.txt

# 4. 重新同步环境
uv pip sync requirements.txt

注意事项

与 pip 命令对比

UV 提供了更统一、更快速的 Python 项目管理体验，特别适合现代 Python 开发工作流。