python uv 简介

一、uv简述

uv 是由 Astral 公司开发、用 Rust 编写的极速 Python 包管理器与项目管理工具，对标 pip、pipenv、poetry，速度远超传统工具。可以实现不同项目使用不同的python版本。

二、常用命令

项目管理

命令	说明
uv init	初始化新项目（生成 pyproject.toml + .python-version）
uv init my-project	在新目录初始化项目
uv add <pkg>	添加依赖到项目（自动更新 pyproject.toml + uv.lock）
uv add --dev <pkg>	添加开发依赖
uv remove <pkg>	移除依赖
uv sync	同步项目环境（按 uv.lock 安装所有依赖）
uv lock	仅更新锁文件，不安装
uv run <cmd>	在项目虚拟环境中运行命令
uv run app.py	运行 Python 脚本
uv run pytest	在项目环境中跑测试

Python 版本管理

命令	说明
uv python install 3.12	安装 Python 3.12
uv python install 3.11 3.13	同时安装多个版本
uv python list	查看可用 Python 版本
uv python list --only-installed	只看已安装的版本
uv python pin 3.12	固定项目使用的 Python 版本
uv python find 3.12	查找本地 3.12 路径

工具安装（全局 CLI 工具）

命令	说明
uv tool install ruff	全局安装一个 CLI 工具（类似 pipx）
uv tool install black --with pytest	安装工具 + 附带依赖
uv tool run ruff check .	临时运行工具（不永久安装）
uv tool list	查看已安装的工具
uv tool upgrade ruff	升级工具
uv tool uninstall ruff	卸载工具

一次性运行（无需项目）

命令	说明
uvx ruff check .	等同于 uv tool run ruff check .
uv run --with requests python -c "import requests; ..."	临时注入依赖运行

pip 兼容模式

命令	说明
uv pip install <pkg>	pip 风格安装（无锁文件）
uv pip install -r requirements.txt	从 requirements.txt 安装
uv pip install -e .	可编辑模式安装
uv pip uninstall <pkg>	卸载
uv pip list	列出已安装包
uv pip freeze > requirements.txt	导出依赖列表
uv pip compile requirements.in -o requirements.txt	编译依赖为锁定文件

虚拟环境

命令	说明
uv venv	在当前目录创建 .venv
uv venv --python 3.12	指定 Python 版本创建
uv venv .venv	指定路径创建

构建 & 发布

命令	说明
uv build	构建项目发行包（wheel + sdist）
uv publish	发布到 PyPI
uv publish --token <token>	使用 token 发布

三、uv在项目中的使用

#安装python版本
uv python install 3.12

#查看Python版本
uv python list

#指定命令执行所在项目使用的版本。（生成或者修改.python-version）
uv python pin 3.12 

#初始化新项目（生成 `pyproject.toml` + `.python-version`）,支持创建目录或者指定python的版本
uv init
uv init 目录
uv init -p 3.12
uv init 目录 -p 3.12

#按照在当前目录创建 `.venv`环境
uv venv

#同步项目环境（创建 `.venv`环境 + 按`uv.lock` 安装所有依赖）
uv sync  

#添加依赖到项目（创建 `.venv`环境 + 自动更新 `pyproject.toml` + `uv.lock`并且安装相关依赖）
uv add "mcp[cli]"

所以项目中一般使用uv init 目录 -p 3.12和uv add就可以。

如果需要在不同项目中使用不同版本，先安装不同版本的python，初始化项目时指定python版本即可，或者通过uv python pin指定。

1. .python-version 是项目级别的------每个项目各自一个文件，互不干扰
2. 优先级顺序 ：.python-version 文件 > pyproject.toml 中的 requires-python > 全局默认