1.环境验证

安装完成后，在终端执行以下命令，输出版本信息即表示安装成功：

uv --version

若提示「uv 不是内部或外部命令」，检查环境变量是否配置正确（macOS/Linux 可执行 source $HOME/\.local/bin/env 刷新环境变量）。

2.核心功能实操（最常用，必掌握）

UV 的核心功能分为 3 部分：Python 版本管理、虚拟环境管理、包管理，下面逐一拆解，每一步都附实操命令和说明。

2.1 Python 版本管理（无需 pyenv，一键搞定）

很多开发者需要同时处理多个 Python 版本的项目（比如有的项目用 3.9，有的用 3.12），UV 可以直接下载、切换版本，无需额外安装 pyenv。

2.1.1 查看所有可用 Python 版本

执行以下命令，可查看所有可下载、已安装的 Python 版本（包括 CPython、PyPy）：

uv python list

（1）安装最新稳定版 Python 3.12

uv python install 3.12

（2）安装指定具体版本（如 3.11.6，避免版本兼容问题）

uv python install 3.11.6

（3）安装 PyPy 版本（轻量高效，适合生产环境）

uv python install pypy3.10

2.1.2设置全局默认 Python 版本

设置后，所有终端都会使用该版本的 Python，无需每次切换：

uv python default 3.12

验证是否生效：

python --version # 输出 Python 3.12.x 即成功

2.1.3 固定项目 Python 版本（团队协作必备）

在项目根目录执行以下命令，会生成 .python-version 文件，标识项目所需 Python 版本，他人克隆项目后可快速适配：

uv python pin 3.11 # 固定为 3.11 版本

2.2 虚拟环境管理（隔离依赖，避免冲突）

虚拟环境是 Python 开发的必备技巧，可隔离不同项目的依赖包（比如 A 项目用 requests 2.20，B 项目用 requests 2.31），UV 创建和激活虚拟环境的操作比 virtualenv 更简洁。

2.2.1 创建虚拟环境（4种常用方式）

(1)方式1：创建默认名称（.venv）的虚拟环境（推荐，符合行业规范）

uv venv

(2) 方式2：指定 Python 版本创建虚拟环境（如 3.11）

uv venv --python 3.11 .venv
uv venv --python=3.11 .venv # 两种写法均可

(3)方式3：创建自定义名称的虚拟环境（区分不同项目）

uv venv --python 3.12 .venv312 # 适配 Python 3.12 项目

(4)方式4：指定本地已安装的 Python 可执行文件路径（Windows 专用）

uv venv --python "C:\Python311\python.exe" .venv

2.2.2 激活虚拟环境（不同系统操作不同）

激活后，终端提示符前会出现 (.venv) 或自定义名称标识，此时安装的包仅作用于当前虚拟环境：

(1)macOS/Linux 系统（终端执行）

source .venv/bin/activate

(2)Windows 系统（CMD/PowerShell 执行）

.venv\Scripts\activate
.venv37\Scripts\activate # 自定义名称环境激活

2.2.3 验证虚拟环境是否激活

python -VV # 查看当前环境的 Python 版本，确认与虚拟环境指定版本一致

2.2.4 退出虚拟环境（任意系统通用）

deactivate

2.3 包管理（替代 pip ，更快更高效）

UV 的 uv pip 命令完全兼容 pip 的所有功能，且下载速度更快、依赖解析更精准，还支持全局缓存，重复安装包时无需重新下载。

2.3.1 安装包（常用场景）

(1)安装最新版本的包（如 requests）

uv pip install requests

(2)安装指定版本的包（避免版本兼容问题）

uv pip install requests==2.31.0

(3)从 requirements.txt 文件批量安装依赖（迁移项目必备）

uv pip install -r requirements.txt

(4)安装包到开发环境（仅开发时使用，如测试工具 pytest）

uv pip install --dev pytest

2.3.2 升级与卸载包

(1)升级指定包到最新版本

uv pip upgrade requests

(2)升级所有已安装的包（谨慎使用，避免版本冲突）

uv pip upgrade --all

(3)卸载指定包（彻底删除，无残留）

uv pip uninstall requests

2.3.3 导出依赖（项目迁移、协作必备）

将当前环境的依赖包导出为 requirements.txt 文件，方便他人克隆项目后快速安装依赖：

(1)导出当前环境所有依赖（包括开发依赖）

uv pip freeze > requirements.txt

(2)导出生产环境依赖（排除开发依赖，上线必备）

uv pip freeze --production > requirements.txt

2.3.4 临时指定国内镜像源（解决下载缓慢）

若默认镜像源下载缓慢，可临时指定国内镜像源（如阿里云）：

uv pip install requests -i https://mirrors.aliyun.com/pypi/simple/

python -m ensurepip --upgrade

python -m pip install --upgrade pip