UV环境

概述

uv 的作用是管理python版本、python虚拟环境、依赖安装等，uv 是一套现代化的开发环境解决方案，它能够确保构建过程简单、可复现；因此使用了uv之后，就不要再安装python虚拟环境了。

uv 是高性能 Python 包管理与环境工具，本质目标是替代 pip + venv + pip-tools + poetry 的组合，并在速度与可复现性上做优化。

uv 会在项目目录创建 .venv，并通过 标准的 venv 机制 构建隔离的虚拟环境，因此 uv 的虚拟环境与 venv 创建的环境是兼容的。

uv 对依赖下载做了优化，不仅下载快，下载后的依赖还会自动进行全部缓存；如果某个项目需要下载的依赖已在全局缓存，则依赖将被瞬间拷贝到项目中；uv 会生成依赖树文件 uv.lock，以便快速安装依赖。

解释器

用 uv 安装的 Python 不会放在项目目录里，而是放在用户级的全局缓存目录中，由 uv 统一管理、多个项目复用。

全局 python 路径通常为 ~/.local/share/uv/python/，虽然当前项目的 .venv 是“隔离环境”，但解释器本体来自全局缓存，如下：

全局缓存：
   uv/python/cpython-3.12.x/

项目虚拟环境：
.venv/
   bin/python → 指向全局解释器
   lib/site-packages → 项目独立

以上设计指在：

- 避免每个项目都安装一个完整 Python

- 多项目复用解释器

- 提高 CI 和 Docker 构建速度

- 避免依赖系统 Python

基本使用

a> uv执行命令

可以使用uv 直接进入虚拟环境或执行命令，但因为 uv 可以直接以虚拟环境执行命令，因此有了 uv 后，一般不需要再进入虚拟环境了。

在当前项目中直接使用 uv 执行 python 文件时，uv 会自动找到当前项目下的 .venv 虚拟环境，然后临时调整 PATH，并在该环境中执行命令，不会污染当前 shell；如下：

uv run python main.py
或
uv run pytest

如下，也可调用当前项目中的解释器

./.venv/bin/python main.py

b> 依赖文件：

pyproject.toml 是依赖文件，相当于 package.json，uv.lock 相当于 package.json.lock；

pyproject.toml 中的依赖定义是类似 fastapi>=0.100，而 uv.lock 则是具体的锁定版本 0.115.0；

c> 安装工具：

使用命令 uv tool install 可以安装 Python 编写的独立命令行工具；如下：

## 安装工具 
uv tool install ruff 

## 卸载工具 
uv tool uninstall ruff 

## 查看已安装的所有工具列表 
uv tool list 

## 更新工具
uv tool upgrade ruff

使用 uv tool install 安装工具时，uv 会检查本地是否有该工具所需的 python 版本，如果没有，则自动下载安装所需的 python 版本。

uv 会创建一个完全独立的虚拟环境来安装工具，但该工具环境中的 python 解释器依然引用自 uv 全局管理的 python。

如果使用 uv 删除了某个 python 版本，会导致有些工具无法运行；此时，可执行 uv tool upgrade --all 命令来更新所有工具；uv 会自动检测和更新所有工具，如果发现某个工具的独立环境已损坏或所引用的 python 版本已被删除，则 uv 会自动在本地寻找兼容该工具的其它 python 版本，并重新构建工具的独立环境；如果 uv 在本地找不到兼容的 python 版本，就自动下载、安装兼容的 python 版本，并重新为工具构建虚拟环境。

d> python 版本

当执行 uv python list 命令查看已安装的 python 版本时，会显示很多 python 版本；有些没有安装，但支持安装的 python 版本也被列了出来，如下图：

CPython (标准版)：这是官方版本，用 C 语言编写；它兼容性最好，所有的库（如 Pandas, PyTorch）都优先支持它。

PyPy (高性能版)：使用 JIT（即时编译）技术；对于纯 Python 代码（比如大量的循环计算），它的运行速度通常比 CPython 快 5 倍以上。

GraalPy (生态融合版)：由 Oracle 开发，旨在让 Python 能在 Java 的虚拟（JVM）上运行，并方便地与 Java、JavaScript 等语言互相调用。

uv 常用命令

## 安装 Python
uv python install 3.12
uv python install 3.11

## 查看已安装版本
uv python list

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

## 指定版本创建虚拟环境
uv venv --python 3.12
或：
uv venv --python 3.12.2

## 删除环境（直接删除目录）
rm -rf .venv

## 运行命令
uv run python main.py
uv run pytest
uv run ruff check .

## 添加依赖（uv会自动写入 pyproject.toml、生成或更新 uv.lock，并安装到 .venv）
uv add fastapi
uv add requests

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

## 从 Git 安装依赖
uv add git+https://github.com/xxx/xxx.git

## 删除依赖
uv remove fastapi

## 同步依赖（按 lockfile），即读取并根据 pyproject.toml 或 uv.lock 文件，在当前目录下创建或更新虚拟环境
uv sync

## 安装 CLI 工具
uv tool install ruff
uv tool install black

## 从 Git 安装 CLI 工具，并将工具命令为 mytool （ 安装后通过 mytool 在命令行使用该工具 ）
uv tool install mytool --from git+https://github.com/xxx/repo.git

## 查看已安装工具
uv tool list

## 卸载工具
uv tool uninstall ruff

## 查看缓存目录
uv cache dir

## 清理缓存
uv cache clean