LoongLee's blog

UV使用指南

UV使用指南

来源

原始文档: UV_use指南.md

核心内容

UV 是 Astral 团队开发的 Python 包管理和虚拟环境工具,使用 Rust 编写,速度极快。

安装

# 官方安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或使用 wget
wget -qO- https://astral.sh/uv/install.sh | sh

虚拟环境管理

# 创建虚拟环境
uv venv .venv
uv venv .venv --python 3.11

# 项目外创建(推荐)
uv venv ~/.virtualenvs/myproject --python 3.10

# 激活
source .venv/bin/activate

# 指定 Python 版本创建
uv venv --python $(pyenv which python)

包管理

# 安装依赖
uv pip install fastapi uvicorn

# 生成依赖文件
uv pip freeze > requirements.txt

# 卸载
uv pip uninstall requests

# 清缓存
uv cache clean

项目命令

命令 功能
uv init 创建新项目
uv add 添加依赖
uv remove 移除依赖
uv sync 同步环境
uv lock 生成锁文件
uv run 运行命令
uv build 构建包
uv publish 发布到 PyPI
uv tree 显示依赖树
uv format 格式化代码

标准项目结构

project/
├── .venv/
├── pyproject.toml
├── uv.lock
└── app.py

使用 pyproject.toml

[project]
name = "my-app"
version = "0.1.0"
dependencies = [
  "fastapi",
  "uvicorn",
  "requests",
]

环境复现(CI/生产)

uv sync
uv sync --frozen --no-dev

UV + direnv 自动激活

# 1. 安装 direnv
sudo apt install direnv  # Ubuntu/Debian
brew install direnv      # macOS

# 2. 启用 direnv
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc

# 3. 创建项目外虚拟环境
uv venv ~/.virtualenvs/myproject --python 3.10

# 4. 创建 .envrc
cd ~/projects/myproject
echo "source ~/.virtualenvs/myproject/bin/activate" > .envrc

# 5. 授权
direnv allow

效果: - cd myproject → 自动激活 venv - cd .. → 自动退出 - 项目目录干净,无 .venv

关键要点

  • UV 比 pip 快 10-100 倍
  • uv.lock 相当于 poetry.lock,保证环境一致性
  • uv sync --frozen 严格按锁文件安装,不升级
  • 与 pyenv 配合: pyenv 管版本,uv 管环境和依赖

相关实体

  • UV - Python 包管理器
  • Python - Python 编程语言
  • pip - Python 包安装器
  • poetry - Python 依赖管理工具
  • direnv - 目录环境管理器