Python 环境管理新标杆：UV核心命令完全指南

UV工具定位：极速Python环境管理

UV是Astral团队开发的下一代Python环境管理工具，其核心优势在于：

• ⚡ 速度革命：依赖解析比pip快10-100倍
• 🪶 轻量设计：环境创建仅需0.05秒
• 🔒 安全可靠：内置依赖锁定机制
• 🔄 无缝迁移：兼容现有pip工作流

安装命令：pipx install uv（推荐）或 pip install uv

---

核心命令详解手册

1. uv venv：闪电环境创建

功能：创建轻量级虚拟环境

# 基础用法（默认创建.venv）
uv venv

# 指定Python版本
uv venv --python 3.11

# 包含系统包（类似--system-site-packages）
uv venv --system

# 自定义路径
uv venv --path ~/envs/project-env

环境结构：

.venv/
├── bin           # Unix可执行文件
│   ├── python
│   ├── pip
├── Scripts       # Windows可执行文件
│   ├── python.exe
│   ├── pip.exe
└── pyvenv.cfg    # 环境配置文件

---

2. uv pip：极速依赖管理

功能：高性能依赖安装与解析

# 安装单个包
uv pip install numpy

# 批量安装
uv pip install pandas matplotlib seaborn

# 安装指定版本
uv pip install "django>=4.0,<5.0"

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

# 生成锁定文件
uv pip compile pyproject.toml -o requirements.lock

# 哈希验证安装（安全部署）
uv pip install -r requirements.lock --generate-hashes

性能对比：

传统pip: 23.5秒  |  UV pip: 1.8秒  (相同依赖集)

---

3. uv run：智能脚本执行

功能：在UV环境中无缝运行命令

# 运行Python脚本
uv run app.py

# 传递参数
uv run train_model.py --epochs 50 --batch-size 32

# 执行模块
uv run -m pytest tests/

# 临时环境运行（自动清理）
uv run --temp "import sys; print(sys.executable)"

# 指定环境运行
uv run --venv dev-env manage.py migrate

---

4. uv python：解析器管理

功能：Python解释器版本管理

# 列出所有可用Python
uv python list

# 输出示例：
Available Pythons:
* /usr/bin/python3.12 (default)
  /opt/homebrew/bin/python3.11
  ~/.pyenv/versions/3.10.9/bin/python

# 设置默认Python版本
uv use 3.11

# 验证版本
uv python --version

---

5. uv cache：缓存优化

功能：管理依赖缓存加速安装

# 查看缓存信息
uv cache info

# 清理所有缓存
uv cache clean --all

# 保留最近3个版本的缓存
uv cache clean --keep-latest 3

# 指定缓存目录
uv cache dir ~/custom_uv_cache

---

6. uv use：版本切换

功能：动态切换Python版本

# 查看当前版本
uv use current

# 切换到3.10
uv use 3.10

# 全局设置默认版本
uv use --global 3.11

# 项目级版本配置（pyproject.toml）
[tool.uv]
python = "3.11"  # 固定版本

---

7. uv init：项目初始化

功能：一站式项目初始化

# 交互式创建项目
uv init

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

# 创建并安装依赖
uv init --install

# 完整初始化流程
uv init --python 3.11 --name my-project --install

自动生成：

1. 虚拟环境 .venv
2. 基础 requirements.txt
3. 项目结构模板

---

综合应用示例

场景：创建Django项目

# 1. 初始化项目
uv init --python 3.11 --name django-project --install

# 2. 安装依赖
uv pip install django gunicorn psycopg2

# 3. 创建Django项目
uv run django-admin startproject core .

# 4. 启动开发服务器
uv run python manage.py runserver

提示：需要通过uv run创建.venv虚拟目录环境后才能使用uv pip install

场景：CI/CD流水线

.gitlab-ci.yml配置：

test:
  script:
    - pipx install uv  # 安装UV
    - uv venv
    - uv pip install -r requirements.txt
    - uv run pytest tests/
  cache:
    paths:
      - .venv/
      - ~/.cache/uv/

---

命令速查表

命令	功能	高频参数
uv venv	创建环境	--name --python --system
uv pip	包管理	install compile --generate-hashes
uv run	执行命令	--temp --venv -m
uv python	解释器管理	list --version
uv cache	缓存管理	info clean dir
uv use	版本切换	current 3.11 --global
uv init	项目初始化	--python --install --name

提示：所有命令支持 --help 查看详细帮助，如 uv venv --help

命项目实战

# 项目初始化
uv init

# 创建虚拟环境
uv venv

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

# 激活环境
.venv\Scripts\activate

# 添加依赖（会更新 pyproject.toml）
uv add flask

# 可选：添加开发依赖（如调试工具）
uv add --dev flask-debugtoolbar  # 开发环境用的调试工具栏

# 同步项目依赖
uv sync

在项目根目录修改 main.py 文件，写入基础代码

from flask import Flask

app = Flask(__name__)

@app.route('/')
def hello():
    return "Hello, Flask with uv!"

if __name__ == '__main__':
    app.run(debug=True)  # 调试模式，代码修改后自动重启
	

运行 Flask 项目

方法 1：直接通过 Python 执行

# 运行 Flask 应用
python main.py

方法 2：使用 uv run 直接运行（无需手动激活环境）

uv run main.py

方法 3：使用flask命令运行

flask --app main run -p 5000

最佳实践总结

1. 环境创建：项目根目录使用默认 .venv
2. 依赖安装：优先 uv pip compile 生成锁定文件
3. 版本控制：项目内配置 pyproject.toml 固定版本
4. CI/CD优化：复用UV缓存目录加速构建
5. 多项目管理：--name 参数区分不同环境

通过掌握这7大核心命令，您将彻底掌控Python环境管理，实现开发效率的指数级提升！访问官方文档获取最新功能。