uv 精简使用教程

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

---

一、安装 uv

# 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

验证安装：

uv --version

---

二、包管理（对标 pip）

安装包

uv pip install requests

_{等同于 pip install requests}

安装指定版本

uv pip install requests==2.31.0

_{等同于 pip install requests==2.31.0}

批量安装依赖

uv pip install -r requirements.txt

_{等同于 pip install -r requirements.txt}

卸载包

uv pip uninstall requests

_{等同于 pip uninstall requests}

查看已安装的包

uv pip list

_{等同于 pip list}

查看包详情

uv pip show requests

_{等同于 pip show requests}

导出依赖

uv pip freeze > requirements.txt

_{等同于 pip freeze > requirements.txt}

升级包

uv pip install --upgrade requests

_{等同于 pip install --upgrade requests}

---

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

创建虚拟环境

uv venv

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

指定目录 / Python 版本

uv venv myenv --python 3.12

_{等同于 python3.12 -m venv myenv}

激活虚拟环境

# macOS / Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

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

---

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

初始化项目

uv init myproject
cd myproject

_{pip 没有对应功能，类似 poetry init}

添加依赖

uv add requests
uv add "flask>=3.0"

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

移除依赖

uv remove requests

_{pip 没有对应功能，类似 poetry remove requests}

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

uv sync

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

运行脚本

uv run python main.py
uv run flask run

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

---

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

安装 Python

uv python install 3.12

_{等同于 pyenv install 3.12}

查看可用版本

uv python list

_{等同于 pyenv versions}

固定项目 Python 版本

uv python pin 3.12

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

---

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

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

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

全局安装工具

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）