uv 管理python环境

uv是新一代的Python项目管理工具，具备开发一个完整项目的所有功能点：

功能点	描述
包管理	完全替代pip的功能，支持包的安装、升级、卸载等操作
虚拟环境管理	内置虚拟环境创建和管理，无需额外安装virtualenv或venv
依赖解析与锁定	提供智能依赖解析算法并生成锁定文件(uv.lock)
Python版本管理	能够自动安装和管理不同版本的Python解释器
项目初始化	通过uv init快速创建新项目并生成标准结构
脚本运行	支持在虚拟环境中直接运行脚本而无需手动激活环境
包发布	内置支持将项目打包并发布到PyPI等仓库

安装

# On Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On macOS
brew install uv

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

# With pip.
pip install uv

用法

1. 命令简介

uv包含以下命令，前几个是比较常用的。

命令	描述
run	运行命令或脚本
init	创建一个新项目
add	向项目中添加依赖项
remove	从项目中移除依赖项
sync	更新项目的环境
lock	更新项目的锁定文件
export	将项目的锁定文件导出为其他格式
tree	显示项目的依赖树
tool	运行和安装由 Python 包提供的命令
python	管理 Python 版本和安装
pip	使用兼容 pip 的接口管理 Python 包
venv	创建虚拟环境
build	将 Python 包构建为源代码分发包和 wheels
publish	将分发包上传到索引
cache	管理 uv 的缓存
self	管理 uv 可执行文件
version	显示 uv 的版本
generate-shell-completion	生成 shell 自动补全脚本
help	显示某个命令的文档

2. 文件结构

首先执行以下命令初始化一个项目：

uv init test-uv

项目结构：

test-uv
    ├─ .git
    ├─.gitignore
    ├─.python-version
    ├─README.md
    ├─main.py
    ├─pyproject.toml

以看到项目中除了Python相关的脚本外，还生成了git，用于版本管理。

# pyproject.toml
[project]
name = "test-uv"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.9"
dependencies = []

pyproject.toml是项目配置信息，类似于JS中的package.json。

# python-version
3.10

.python-version记录了当前项目使用的Python环境版本，可以自行编辑修改。

3. 运行脚本

uv中执行脚本的启动命令为：

# 与JS中`npm run dev`类似
uv run xxx

uv run 的执行逻辑为：

1. 检查当前目录中是否存在 .venv目录，若不存在则创建新环境
2. 验证环境是否包含脚本所需依赖，如果缺失依赖则自动安装
3. 在当前的虚拟环境中执行命令，不会与其他环境产生冲突

以下是uv启动命令与常规Python启动命令的对比：

执行命令	环境处理
uv run xxx	自动关联虚拟环境： - 优先使用当前目录下的 .venv - 若不存在会自动创建 - 无需手动激活/停用
python xxx.py	依赖当前Shell环境： - 需手动激活虚拟环境

4. 管理依赖

4.1 创建venv环境

#如果需要指定 Python 版本，可以添加 `--python=3.11` 等参数
uv venv .venv --python3.11

4.2 激活虚拟环境（可选)

# 激活环境
source .venv/bin/activate

# 退出虚拟环境
deactivate

4.3 添加项目依赖

如果已经存在pyproject.toml文件，可以添加项目依赖

uv sync

4.4 add

用于安装包并自动更新项目配置文件（pyproject.toml）和锁定文件（uv.lock）

# 安装最新版包
uv add requests

# 安装指定版本
uv add "flask>=2.0.0"

uv add git+https://github.com/psf/requests.git

uv add 可以理解为 uv pip install的增强版，底层同样是利用了pip进行安装，但是uv add额外增加了更新项目配置文件的功能

4.5 remove

用于卸载包并更新项目配置

# 删除依赖
uv remove fastapi

# 清理缓存
uv cache clean

4.6 sync

根据锁定文件精确还原依赖环境

# 同步所有依赖（包括dev）
uv sync

# 仅同步生产依赖
uv sync --production

# 同步并清理多余包
uv sync --clean

# 更新依赖
uv sync --upgrade

# 更新特定包 
uv sync --upgrade-package flask

4.7 lock

创建/更新 uv.lock文件，用于跨平台精确版本记录

# 生成新锁定文件
uv lock

# 检查更新但不写入（dry-run）
uv lock --check

# 强制重新解析
uv lock --update

4.8 tree

用于可视化展示依赖关系

# 显示完整依赖树
uv tree

# 仅显示指定包的依赖路径
uv tree flask

# 反向追溯依赖（谁依赖了这个包）
uv tree --reverse sqlalchemy

# 输出为JSON格式
uv tree --format json

5. 管理Python环境

基本命令：

uv python [OPTIONS] <COMMAND>

可选参数如下：

命令	描述
list	列出可用的Python安装版本
install	下载并安装Python版本
find	显示当前Python安装位置
pin	固定使用特定Python版本
dir	显示uv Python安装目录
uninstall	卸载Python版本

uv python list
cpython-3.14.0a5+freethreaded-macos-aarch64-none    <download available>
cpython-3.14.0a5-macos-aarch64-none                 <download available>
cpython-3.13.2+freethreaded-macos-aarch64-none      <download available>
cpython-3.13.2-macos-aarch64-none                   /opt/homebrew/opt/[email protected]/bin/python3.13 -> ../Frameworks/Python.framework/Versions/3.13/bin/python3.13
cpython-3.13.2-macos-aarch64-none                   <download available>
cpython-3.12.9-macos-aarch64-none                   /opt/homebrew/opt/[email protected]/bin/python3.12 -> ../Frameworks/Python.framework/Versions/3.12/bin/python3.12
cpython-3.12.9-macos-aarch64-none                   <download available>
cpython-3.11.11-macos-aarch64-none                  /opt/homebrew/opt/[email protected]/bin/python3.11 -> ../Frameworks/Python.framework/Versions/3.11/bin/python3.11
cpython-3.11.11-macos-aarch64-none                  <download available>
cpython-3.10.16-macos-aarch64-none                  /Users/.local/share/uv/python/cpython-3.10.16-macos-aarch64-none/bin/python3.10
cpython-3.9.21-macos-aarch64-none                   /opt/homebrew/opt/[email protected]/bin/python3.9 -> ../Frameworks/Python.framework/Versions/3.9/bin/python3.9
cpython-3.9.21-macos-aarch64-none                   <download available>
cpython-3.9.12-macos-aarch64-none                   /Users/opt/anaconda3/bin/python3.9
cpython-3.9.12-macos-aarch64-none                   /Users/opt/anaconda3/bin/python3 -> python3.9
cpython-3.9.12-macos-aarch64-none                   /Users/opt/anaconda3/bin/python -> python3.9
cpython-3.9.6-macos-aarch64-none                    /Library/Developer/CommandLineTools/usr/bin/python3 -> ../../Library/Frameworks/Python3.framework/Versions/3.9/bin/python3
cpython-3.8.20-macos-aarch64-none                   <download available>
pypy-3.11.11-macos-aarch64-none                     <download available>
pypy-3.10.16-macos-aarch64-none                     <download available>
pypy-3.9.19-macos-aarch64-none                      <download available>

python环境并不完全都是新的，会根据本地已有的环境添加软连接，如brew安装的python3.11～python3.13和conda的python3.9都被添加软连接进行复用。 而<download available>则表示当前本地环境没有，uv可以下载的版本。

uv python install python3.8

总结

uv越来越频繁的出现在一些新的项目中，如最近特别多的MCP项目，基本都是用uv进行管理的。比pip更快，比conda更可靠，具备软件开发的完整功能，对于不熟悉Python项目的其他软件开发者来说也降低了学习门槛。如果是开发新的项目，不妨使用uv来进行管理吧，相信会有全新的体验。