整理uv常用命令

uv 是一个高速 Python 包与项目管理工具，可替代常见的 pip、venv、pip-tools 和部分 pipx 工作流。新项目建议优先使用 uv init / add / run / sync，而不是直接使用 uv pip。官方文档

安装与检查

# Windows PowerShell 安装
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 查看版本
uv --version

# 更新 uv
uv self update

# 查看帮助
uv --help
uv add --help

项目管理

# 创建新项目
uv init my-project
cd my-project

# 在当前目录初始化
uv init

# 指定 Python 版本
uv init --python 3.12

# 运行项目
uv run main.py

# 运行模块
uv run python -m package_name

# 执行项目内命令
uv run pytest
uv run ruff check .

uv run 会自动检查并同步 .venv、uv.lock 与 pyproject.toml，通常不需要手动激活虚拟环境。运行命令说明

依赖管理

# 添加依赖
uv add requests
uv add "fastapi>=0.115"
uv add requests rich pydantic

# 添加开发依赖
uv add --dev pytest ruff

# 从 requirements.txt 添加
uv add -r requirements.txt

# 删除依赖
uv remove requests

# 查看依赖树
uv tree

锁定与同步

# 根据 pyproject.toml 更新 uv.lock
uv lock

# 创建或更新 .venv，使其与锁文件一致
uv sync

# 不更新锁文件，严格按现有锁文件同步
uv sync --frozen

# 升级所有依赖
uv lock --upgrade

# 升级指定依赖
uv lock --upgrade-package requests

团队协作时通常提交：

pyproject.toml
uv.lock

其他成员拉取代码后执行：

uv sync
uv run main.py

Python 版本管理

# 查看可用或已安装版本
uv python list

# 安装 Python
uv python install 3.12

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

# 查找 Python 路径
uv python find

虚拟环境

# 创建默认 .venv
uv venv

# 指定 Python
uv venv --python 3.12

# 指定虚拟环境目录
uv venv .venv-test

# Windows PowerShell 手动激活
.venv\Scripts\Activate.ps1

# 退出
deactivate

使用 uv run 时一般不需要激活环境。虚拟环境说明

兼容 pip 的用法

适合旧项目或仅管理虚拟环境，不会自动修改 pyproject.toml：

uv venv
uv pip install requests
uv pip install -r requirements.txt
uv pip uninstall requests

uv pip list
uv pip show requests
uv pip freeze
uv pip check
uv pip tree

# 严格同步 requirements.txt，多余依赖会被删除
uv pip sync requirements.txt

注意：uv pip 是兼容接口，但底层并不会调用真正的 pip。pip 接口说明

临时或全局命令行工具

# 临时运行工具，无需安装到当前项目
uvx ruff check .
uvx pycowsay hello

# 等价写法
uv tool run ruff check .

# 安装为用户级工具
uv tool install ruff

# 查看和卸载
uv tool list
uv tool uninstall ruff

# 将工具目录加入 PATH
uv tool update-shell

构建与发布

# 构建 wheel 和源码包
uv build

# 发布到包索引
uv publish

# 导出 requirements.txt
uv export --format requirements-txt --output-file requirements.txt

最常用的一套流程可以浓缩为：

uv init my-project
cd my-project
uv python pin 3.12
uv add requests
uv add --dev pytest ruff
uv run pytest
uv run python main.py