uv 精简使用教程

uv --- 由 Rust 编写的极速 Python 包管理器，速度比 pip 快 10-100 倍。

一、安装 uv

bash 复制代码

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

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

# 通过 pip 安装（如果你更习惯）
pip install uv

# 通过 Homebrew 安装
brew install uv

验证安装：

bash 复制代码

uv --version

二、包管理（对标 pip）

安装包

bash 复制代码

uv pip install requests

~等同于 pip install requests~

安装指定版本

bash 复制代码

uv pip install requests==2.31.0

~等同于 pip install requests==2.31.0~

批量安装依赖

bash 复制代码

uv pip install -r requirements.txt

~等同于 pip install -r requirements.txt~

卸载包

bash 复制代码

uv pip uninstall requests

~等同于 pip uninstall requests~

查看已安装的包

bash 复制代码

uv pip list

~等同于 pip list~

查看包详情

bash 复制代码

uv pip show requests

~等同于 pip show requests~

导出依赖

bash 复制代码

uv pip freeze > requirements.txt

~等同于 pip freeze > requirements.txt~

升级包

bash 复制代码

uv pip install --upgrade requests

~等同于 pip install --upgrade requests~

三、虚拟环境管理（对标 python -m venv）

创建虚拟环境

bash 复制代码

uv venv

~等同于 python -m venv .venv，默认在当前目录创建 .venv~

指定目录 / Python 版本

bash 复制代码

uv venv myenv --python 3.12

~等同于 python3.12 -m venv myenv~

激活虚拟环境

bash 复制代码

# macOS / Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

~激活方式和传统 venv 一样，uv 不改变这一步~

四、项目管理（uv 独有，对标 pip + venv + pip-tools 组合）

初始化项目

bash 复制代码

uv init myproject
cd myproject

~pip 没有对应功能，类似 poetry init~

添加依赖

bash 复制代码

uv add requests
uv add "flask>=3.0"

~pip 没有对应功能，类似 poetry add requests，会自动写入 pyproject.toml 并锁定版本~

移除依赖

bash 复制代码

uv remove requests

~pip 没有对应功能，类似 poetry remove requests~

同步依赖（按锁文件安装）

bash 复制代码

uv sync

~等同于 pip install -r requirements.txt，但基于 uv.lock 精确锁定~

运行脚本

bash 复制代码

uv run python main.py
uv run flask run

~等同于先激活虚拟环境再 python main.py，uv 会自动处理环境~

五、Python 版本管理（对标 pyenv）

安装 Python

bash 复制代码

uv python install 3.12

~等同于 pyenv install 3.12~

查看可用版本

bash 复制代码

uv python list

~等同于 pyenv versions~

固定项目 Python 版本

bash 复制代码

uv python pin 3.12

~等同于 pyenv local 3.12，会生成 .python-version 文件~

六、一次性运行工具（对标 pipx）

bash 复制代码

uv tool run ruff check .
# 或简写
uvx ruff check .

~等同于 pipx run ruff check .，无需安装即可运行命令行工具~

全局安装工具

bash 复制代码

uv tool install ruff

~等同于 pipx install ruff~

七、常用技巧速查

操作	uv 命令	pip 等价
安装包	`uv pip install pkg`	`pip install pkg`
卸载包	`uv pip uninstall pkg`	`pip uninstall pkg`
列出包	`uv pip list`	`pip list`
导出依赖	`uv pip freeze`	`pip freeze`
创建虚拟环境	`uv venv`	`python -m venv .venv`
初始化项目	`uv init`	(无)
添加依赖	`uv add pkg`	(无，类似 poetry add)
同步依赖	`uv sync`	`pip install -r`
运行脚本	`uv run python x.py`	`python x.py`
安装 Python	`uv python install 3.12`	(无，类似 pyenv)
运行工具	`uvx tool`	(无，类似 pipx run)

八、项目文件结构说明

使用 uv init 后，项目中会出现以下关键文件：

文件	说明
`pyproject.toml`	项目配置和依赖声明（`uv add` 自动维护）
`uv.lock`	精确锁定文件（自动生成，提交到 Git）
`.python-version`	固定 Python 版本（`uv python pin` 生成）
`.venv/`	虚拟环境目录（加入 `.gitignore`）