什么是 uv？

uv 是一个用 Rust 编写的、极快的 Python 包和项目管理工具。由 Astral 公司开发（也是 Ruff 的作者），旨在替代传统的 pip、pip-tools、virtualenv、poetry 等多个工具。

一句话概括

uv 是一个工具，可以做 pip + virtualenv + poetry 三个人做的事，而且速度更快。

---

🚀 核心特性

特性	说明
⚡ 极快速度	比 pip 快 10-100 倍，用 Rust 编写
📦 管理 Python 版本	可安装、切换、管理多个 Python 版本
🔧 管理虚拟环境	创建、激活、删除虚拟环境
📚 管理依赖包	安装、卸载、更新包，替代 pip
📁 管理项目	初始化新项目、锁定依赖版本
✅ 兼容性	完全兼容 pip、requirements.txt、pyproject.toml
🔄 可移植	支持跨平台（Windows、Linux、macOS）

---

📊 与传统工具对比

操作	传统方式	uv 方式
安装 Python	手动下载安装包	uv python install 3.12
创建虚拟环境	python -m venv .venv	uv venv
激活虚拟环境	.venv\Scripts\activate	无需激活（用 uv run）或同样方式激活
安装包	pip install requests	uv pip install requests
安装依赖	pip install -r requirements.txt	uv pip install -r requirements.txt
运行脚本	python script.py	uv run python script.py

---

📋 常用命令一览

text

# Python 版本管理
uv python install 3.12      # 安装 Python
uv python list              # 查看已安装版本

# 虚拟环境管理
uv venv --python 3.12       # 创建虚拟环境
.venv\Scripts\activate      # 激活（与传统方式相同）
uv run python script.py     # 直接运行（无需激活）

# 包管理
uv pip install requests     # 安装包
uv pip install -r requirements.txt  # 批量安装
uv pip list                 # 查看已安装包
uv pip freeze > requirements.txt    # 导出依赖

# 项目管理
uv init                     # 初始化新项目
uv add requests             # 添加依赖（自动更新 pyproject.toml）
uv sync                     # 同步项目依赖

核心架构

bash

D:\
├── tools\
│   └── uv\                 ← uv.exe 所在目录
│
├── uv_python\              ← 所有项目共享的Python解释器
│   ├── 3.12.10\
│   └── 3.11.9\
│
├── uv_cache\               ← uv 缓存目录
│
├── project_A\              ← 项目A
│   ├── .venv\              ← 项目A的虚拟环境
│   └── 代码...
│
└── project_B\              ← 项目B
    ├── .venv\              ← 项目B的虚拟环境
    └── 代码...

📦 第一部分：安装 uv 到 D 盘（也可以指定其他路径）

1.1 以管理员身份打开 PowerShell

1.2 执行自动安装脚本

powershell

# 将 uv 安装到 D:\tools\uv
powershell -ExecutionPolicy ByPass -c "`$env:UV_INSTALL_DIR = 'D:\tools\uv'; irm https://astral.sh/uv/install.ps1 | iex"

1.3 手动配置 PATH（确保全局可用）

1. 按 Win + R，输入 SystemPropertiesAdvanced，回车

2. 点击「环境变量」

3. 在「用户变量」中找到 Path，选中后点击「编辑」

4. 点击「新建」，输入 D:\tools\uv

5. 点击「上移」将其移到顶部

6. 点击「确定」保存所有窗口

1.4 验证安装

关闭并重新打开 PowerShell，执行：

powershell

uv --version

预期输出：uv 0.8.19 或类似版本号

---

🔧 第二部分：配置 uv 环境变量（一次性操作）

2.1 设置 Python 统一安装目录和缓存目录

以管理员身份打开 PowerShell，执行：

powershell

# 设置Python统一安装目录（所有项目共享）
[Environment]::SetEnvironmentVariable("UV_PYTHON_INSTALL_DIR", "D:\tools\uv\uv_python", "User")

# 设置缓存目录（避免C盘占用）
[Environment]::SetEnvironmentVariable("UV_CACHE_DIR", "D:\tools\uv\uv_cache", "User")

2.2 重启终端

关闭所有 PowerShell 窗口，重新打开。

2.3 安装 Python 版本

powershell

# 安装 Python 3.12（推荐）
uv python install 3.12

# 如需 Python 3.11
uv python install 3.11

2.4 验证 Python 安装

powershell

uv python list --only-installed

预期输出：

text

cpython-3.12.10-windows-x86_64-none    D:\uv_python\cpython-3.12.10...

---

📁 第三部分：创建新项目（每个项目重复此步骤）

3.1 进入项目目录

powershell

cd D:\git\你的项目名

3.2 创建虚拟环境

powershell

uv venv --python 3.12 --seed

3.3 安装项目依赖

powershell

# 如果有 requirements.txt
uv pip install -r requirements.txt

# 或手动安装
uv pip install <包名>

3.4 验证环境

powershell

# 方法1：激活后验证
.venv\Scripts\activate
python -c "import sys; print(sys.executable)"
# 应输出：D:\git\项目名\.venv\Scripts\python.exe

python -c "import sys; print(sys.base_prefix)"
# 应输出：D:\tools\uv\uv_python\cpython-3.12.10...

deactivate

# 方法2：直接验证
.venv\Scripts\python.exe -c "import sys; print(sys.base_prefix)"

---

🏃 第四部分：运行 Python 脚本

方法一：激活虚拟环境后运行（推荐，日常开发）

powershell

# 1. 进入项目目录
cd D:\git\你的项目名

# 2. 激活虚拟环境
.venv\Scripts\activate

# 3. 运行脚本（这时终端提示符前会显示环境名）
python your_script.py

# 4. 运行多个脚本或命令
python script1.py
python script2.py --option value

# 5. 工作完成后退出环境
deactivate

特点：

• 激活后所有 python 命令自动使用虚拟环境

• 适合需要连续运行多个脚本的场景

• 终端提示符会显示 (项目名) 便于识别

方法二：使用 uv run（最简洁，推荐）

powershell

# 进入项目目录
cd D:\git\你的项目名

# 直接运行脚本（无需手动激活）
uv run python your_script.py

# 运行带参数的脚本
uv run python your_script.py --input data.txt

# 运行模块
uv run python -m pytest

# 临时执行单条命令
uv run python -c "print('hello')"

特点：

• 无需手动激活/退出环境

• 自动识别项目中的 .venv

• 适合单次运行脚本或快速测试

方法对比

方法	命令	适用场景
方法一（激活后运行）	.venv\Scripts\activate → python script.py	日常开发、连续运行多个脚本
方法二（uv run）	uv run python script.py	快速测试、单次运行、CI/CD

实际操作示例

powershell

# 示例：假设项目中有 main.py

# 方法一
cd D:\git\project_test
.venv\Scripts\activate
python main.py
deactivate

# 方法二
cd D:\git\project_test
uv run python main.py

---

📋 第五部分：日常使用命令速查

操作	命令
环境管理
创建虚拟环境	uv venv --python 3.12 --seed
激活环境	cd D:\git\项目名 → .venv\Scripts\activate
退出环境	deactivate
查看Python路径	python -c "import sys; print(sys.executable)"
python版本管理
安装python版本	uv python install 3.12
卸载已安装的python版本	uv python uninstall 3.12
查看已安装的python版本	uv python list --only-installed
查看可安装的python版本	uv python list
包管理
安装包	uv pip install <包名>
卸载包	uv pip uninstall <包名>
查看依赖	uv pip list
导出依赖	uv pip freeze > requirements.txt
安装所有依赖	uv pip install -r requirements.txt
运行脚本
方法一（激活后）	.venv\Scripts\activate → python script.py
方法三（uv run）	uv run python script.py

---

🚚 第六部分：迁移到新主机

6.1 需要复制的内容

内容	路径
uv 程序	D:\tools\uv
Python统一目录	D:\tools\uv\uv_python
缓存目录（可选）	D:\tools\uv\uv_cache
项目文件夹	D:\git\项目名

6.2 在新主机上的操作

1. 复制整个 D:\tools、D:\tools\uv\uv_python、D:\git 到新主机相同路径

2. 配置 PATH：将 D:\tools\uv 添加到系统 PATH（参考 1.3 步骤）

3. 配置环境变量（参考 2.1 步骤）

4. 重启终端

5. 验证环境：

   powershell

   uv --version
   uv python list --only-installed

6. 进入项目，运行脚本：

   powershell

   cd D:\git\项目名
   uv run python main.py
   # 或
   .venv\Scripts\activate
   python main.py
   deactivate

如果路径发生变化，重建虚拟环境：

powershell

Remove-Item -Recurse -Force .venv
uv venv --python 3.12 --seed
uv pip install -r requirements.txt

---

📝 第七部分：.gitignore 配置

在项目根目录创建 .gitignore：

gitignore

.venv/
__pycache__/
*.pyc
.uv/