uv

js
uv init [name]
uv venv
uv add [package]
uv sync

uv 使用方法整理

适用工具：Astral uv
定位：Python 包管理、虚拟环境、Python 版本、项目依赖与脚本运行工具。
适合替代或覆盖 pip、venv、virtualenv、pip-tools、部分 poetry / pyenv 使用场景。

1. uv 是什么

uv 是 Astral 推出的 Python 包和项目管理工具，使用 Rust 编写，特点是：

安装和解析依赖速度快
自动管理项目虚拟环境
使用 pyproject.toml 管理项目依赖
使用 uv.lock 锁定依赖版本
可以安装和管理 Python 版本
支持类似 pip 的命令
支持直接运行 Python 脚本和 CLI 工具

如果是新项目，推荐优先使用：

bash
uv init
uv add
uv remove
uv sync
uv run

如果是已有的传统 requirements.txt 项目，可以使用：

bash
uv venv
uv pip install
uv pip sync
uv pip freeze

2. 安装 uv

2.1 Windows PowerShell

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

安装完成后检查：

powershell
uv --version

如果提示找不到 uv，重新打开终端后再执行。

2.2 macOS / Linux

bash
curl -LsSf https://astral.sh/uv/install.sh | sh

检查：

bash
uv --version

2.3 使用 pip 安装

如果已经有 Python，也可以：

bash
pip install uv

不过日常使用更推荐官方独立安装方式，因为 uv 本身并不依赖 Python 才能运行。

3. 最常用工作流

新建一个 Python 项目：

bash
uv init my-project
cd my-project

添加依赖：

bash
uv add requests

添加开发依赖：

bash
uv add --dev pytest

运行 Python：

bash
uv run python main.py

同步项目依赖：

bash
uv sync

移除依赖：

bash
uv remove requests

这基本就是日常开发最常用的一套命令。

4. 创建项目

4.1 创建新项目

bash
uv init my-project

进入项目：

bash
cd my-project

也可以直接在当前目录初始化：

bash
uv init

4.2 创建普通应用

bash
uv init my-app

较新的 uv 版本默认会为应用项目配置现代 Python 项目结构。

4.3 创建 Python 库

bash
uv init --lib my-lib

适合：

Python SDK
公共工具包
可发布到 PyPI 的库

4.4 创建最简单项目

如果只是想写一些脚本，不需要打包：

bash
uv init --no-package

或者：

bash
uv init --bare

5. 项目中常见文件

典型项目中会看到：

text
my-project/
├─ .venv/
├─ .python-version
├─ pyproject.toml
├─ uv.lock
├─ README.md
└─ src/

主要作用：

文件	作用
`pyproject.toml`	项目配置、Python 版本、依赖声明
`uv.lock`	锁定精确依赖版本
`.python-version`	指定项目 Python 版本
`.venv`	项目虚拟环境
`src/`	项目源代码

6. Python 版本管理

uv 可以直接安装和管理 Python。

6.1 查看 Python

bash
uv python list

6.2 安装 Python

例如安装 Python 3.12：

bash
uv python install 3.12

安装 Python 3.13：

bash
uv python install 3.13

6.3 给项目固定 Python 版本

bash
uv python pin 3.12

会生成或更新：

text
.python-version

之后该项目会优先使用指定版本。

6.4 查找 Python

bash
uv python find

指定版本：

bash
uv python find 3.12

6.5 卸载 Python

bash
uv python uninstall 3.12

7. 虚拟环境

7.1 创建虚拟环境

bash
uv venv

默认创建：

text
.venv

指定 Python：

bash
uv venv --python 3.12

7.2 Windows 激活虚拟环境

PowerShell：

powershell
.venv\Scripts\Activate.ps1

CMD：

cmd
.venv\Scripts\activate.bat

7.3 macOS / Linux 激活

bash
source .venv/bin/activate

7.4 是否一定要手动激活？

使用现代 uv 项目模式时，通常不需要。

例如：

bash
uv run python main.py

uv run 会自动使用项目对应的环境。

所以相比：

bash
.venv\Scripts\Activate.ps1
python main.py

更推荐：

bash
uv run python main.py

8. 安装项目依赖

8.1 添加依赖

例如：

bash
uv add requests

多个依赖：

bash
uv add requests pandas numpy

指定版本：

bash
uv add "requests==2.32.5"

指定最低版本：

bash
uv add "fastapi>=0.115"

8.2 添加开发依赖

bash
uv add --dev pytest

例如：

bash
uv add --dev pytest ruff mypy

开发依赖通常用于：

pytest
ruff
mypy
black
coverage

8.3 删除依赖

bash
uv remove requests

删除开发依赖同样使用：

bash
uv remove pytest

9. uv sync

uv sync 用来让本地虚拟环境与项目配置、锁文件保持一致。

bash
uv sync

典型场景：

从 Git 拉下项目：

bash
git clone xxx
cd project
uv sync

即可根据：

text
pyproject.toml
uv.lock

创建并同步项目环境。

通常不需要再：

bash
pip install -r requirements.txt

10. uv.lock

执行：

bash
uv add xxx

或者：

bash
uv lock

会生成：

text
uv.lock

它记录解析后的依赖版本。

建议项目中提交：

text
pyproject.toml
uv.lock

到 Git。

例如：

bash
git add pyproject.toml uv.lock
git commit -m "update dependencies"

11. uv run

这是 uv 非常常用的命令。

11.1 运行 Python 文件

bash
uv run python main.py

11.2 运行 Python 模块

bash
uv run python -m pytest

11.3 运行项目里的工具

例如项目安装了：

bash
uv add --dev pytest

直接：

bash
uv run pytest

无需手动激活 .venv。

11.4 运行 FastAPI

安装：

bash
uv add fastapi uvicorn

运行：

bash
uv run uvicorn main:app --reload

11.5 运行 Django

bash
uv run python manage.py runserver

12. uv pip

uv pip 提供类似传统 pip 的低层接口。

适合：

老项目
requirements.txt 项目
暂时不想改成 pyproject.toml
希望直接替换部分 pip 工作流

注意：

uv pip 并不是内部调用 pip，而是 uv 自己实现的一套兼容接口。

12.1 安装包

先创建环境：

bash
uv venv

然后：

bash
uv pip install requests

安装多个：

bash
uv pip install requests flask pandas

12.2 安装 requirements.txt

bash
uv pip install -r requirements.txt

12.3 卸载包

bash
uv pip uninstall requests

12.4 查看已安装包

bash
uv pip list

12.5 查看包信息

bash
uv pip show requests

12.6 查看依赖树

bash
uv pip tree

12.7 导出类似 requirements.txt 的列表

bash
uv pip freeze

保存：

PowerShell

powershell
uv pip freeze > requirements.txt

Linux / macOS

bash
uv pip freeze > requirements.txt

12.8 检查依赖冲突

bash
uv pip check

13. uv pip sync

假设项目有：

text
requirements.txt

执行：

bash
uv pip sync requirements.txt

它会让当前环境严格与 requirements.txt 保持一致。

与：

bash
uv pip install -r requirements.txt

区别可以简单理解为：

text
install = 安装文件里缺少的依赖
sync    = 把环境同步成文件描述的状态

如果环境里存在 requirements 中没有的包，sync 可能将其移除。

因此 CI、部署、可复现环境中，sync 更合适。

14. requirements.in 工作流

传统 pip-tools 用户可以使用：

bash
uv pip compile requirements.in -o requirements.txt

例如 requirements.in：

text
fastapi
uvicorn
requests

生成：

text
requirements.txt

再同步：

bash
uv pip sync requirements.txt

15. pyproject.toml

例如：

toml
[project]
name = "demo"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115",
    "requests>=2.32",
]

使用：

bash
uv sync

安装依赖。

通常不建议手工维护复杂依赖版本，优先：

bash
uv add fastapi
uv add requests

由 uv 自动修改 pyproject.toml。

16. 指定 Python 版本运行

例如：

bash
uv run --python 3.12 python main.py

或者先：

bash
uv python pin 3.12

再：

bash
uv run python main.py

17. 临时安装依赖运行

如果只想临时运行，不想把依赖加入项目：

bash
uv run --with requests python test.py

多个临时依赖：

bash
uv run --with requests --with pandas python test.py

适合临时脚本和测试。

18. uv tool

uv tool 可以运行或安装 Python CLI 工具，类似 pipx。

18.1 临时运行工具

例如 Ruff：

bash
uvx ruff check .

uvx 可以理解为：

bash
uv tool run

18.2 安装全局工具

bash
uv tool install ruff

之后：

bash
ruff check .

18.3 查看工具

bash
uv tool list

18.4 卸载工具

bash
uv tool uninstall ruff

19. 常用命令速查

需求	命令
查看版本	`uv --version`
初始化项目	`uv init`
新建项目	`uv init demo`
创建库	`uv init --lib demo`
创建虚拟环境	`uv venv`
安装 Python	`uv python install 3.12`
查看 Python	`uv python list`
固定 Python	`uv python pin 3.12`
添加依赖	`uv add requests`
添加开发依赖	`uv add --dev pytest`
删除依赖	`uv remove requests`
同步项目	`uv sync`
更新锁文件	`uv lock`
运行 Python	`uv run python main.py`
运行 pytest	`uv run pytest`
pip 模式安装	`uv pip install requests`
安装 requirements	`uv pip install -r requirements.txt`
同步 requirements	`uv pip sync requirements.txt`
查看安装包	`uv pip list`
查看依赖树	`uv pip tree`
导出包列表	`uv pip freeze`
检查依赖	`uv pip check`
临时运行工具	`uvx ruff check .`

20. pip 与 uv 命令对照

pip / Python	uv
`python -m venv .venv`	`uv venv`
`pip install requests`	`uv pip install requests`
`pip uninstall requests`	`uv pip uninstall requests`
`pip list`	`uv pip list`
`pip freeze`	`uv pip freeze`
`pip install -r requirements.txt`	`uv pip install -r requirements.txt`
`pipx run ruff`	`uvx ruff`

如果使用 uv 项目模式，更推荐：

传统方式	uv 项目模式
修改 requirements	`uv add xxx`
删除 requirements 中依赖	`uv remove xxx`
pip install	`uv sync`
激活环境后运行	`uv run xxx`

21. 推荐的新项目开发流程

第一步：创建项目

bash
uv init my-api
cd my-api

第二步：固定 Python

bash
uv python pin 3.12

如果本机没有：

bash
uv python install 3.12

第三步：添加依赖

bash
uv add fastapi uvicorn

第四步：添加开发依赖

bash
uv add --dev pytest ruff

第五步：开发

bash
uv run uvicorn main:app --reload

第六步：测试

bash
uv run pytest

第七步：代码检查

bash
uv run ruff check .

22. 已有项目迁移到 uv

如果老项目只有：

text
requirements.txt

有两种方案。

方案一：先不改项目结构

最简单：

bash
uv venv
uv pip install -r requirements.txt

运行：

bash
uv run python main.py

这种迁移风险最低。

方案二：迁移为 uv 项目

初始化：

bash
uv init

然后把项目依赖逐步加入：

bash
uv add fastapi
uv add requests
uv add pandas

最终依赖由：

text
pyproject.toml
uv.lock

管理。

推荐新项目和长期维护项目使用这种方式。

23. Git 项目推荐提交内容

推荐提交：

text
pyproject.toml
uv.lock
.python-version
src/
README.md

通常不要提交：

text
.venv/

.gitignore：

gitignore
.venv/
__pycache__/
*.pyc
.pytest_cache/
.ruff_cache/

24. 常见问题

24.1 `uv` 不是内部或外部命令

Windows 安装之后如果出现：

text
uv : 无法将“uv”项识别为 cmdlet...

先：

关闭当前 PowerShell
重新打开终端
执行：

powershell
uv --version

仍然不行，再检查安装目录是否已经加入 PATH。

24.2 不想激活虚拟环境怎么办？

直接：

bash
uv run python main.py

或者：

bash
uv run pytest

这是 uv 推荐的项目使用方式之一。

24.3 uv pip install 提示找不到虚拟环境

先执行：

bash
uv venv

再：

bash
uv pip install requests

uv pip install 默认倾向于向虚拟环境安装，而不是直接污染系统 Python。

24.4 `uv add` 和 `uv pip install` 有什么区别？

`uv add`

bash
uv add requests

属于项目管理方式。

它会维护：

text
pyproject.toml
uv.lock
.venv

适合正式项目。

`uv pip install`

bash
uv pip install requests

更接近传统 pip，只对环境进行包安装操作。

适合：

老项目
临时环境
requirements.txt 项目

新项目优先：

bash
uv add

24.5 `uv sync` 和 `uv pip sync` 区别

项目模式

bash
uv sync

依据：

text
pyproject.toml
uv.lock

同步。

pip 兼容模式

bash
uv pip sync requirements.txt

依据：

text
requirements.txt

同步。

25. Windows PowerShell 推荐流程

如果你主要在 Windows 开发，可以直接记这一套。

新项目

powershell
uv init demo
cd demo

uv python pin 3.12

uv add fastapi uvicorn
uv add --dev pytest ruff

uv run python main.py

已有 requirements.txt 项目

powershell
cd existing-project

uv venv

uv pip install -r requirements.txt

uv run python main.py

FastAPI 项目

powershell
uv init my-api
cd my-api

uv add fastapi uvicorn

uv run uvicorn main:app --reload

26. 最推荐记住的 8 个命令

如果不想记太多，先记住：

bash
uv init
uv python pin 3.12
uv add xxx
uv remove xxx
uv sync
uv run xxx
uv venv
uv pip install xxx

其中现代项目最核心的是：

text
uv init
   ↓
uv add
   ↓
uv sync
   ↓
uv run

27. 建议

新 Python 项目

老项目

先用：

text
uv venv + uv pip install -r requirements.txt

稳定后再考虑迁移。

不建议

在同一个项目里长期混合：

text
pip install
uv pip install
uv add
poetry add

最好固定一种依赖管理方式，否则项目依赖状态容易混乱。

28. 官方资料

uv 官方文档：https://docs.astral.sh/uv/
项目管理：https://docs.astral.sh/uv/guides/projects/
pip 兼容接口：https://docs.astral.sh/uv/pip/
CLI 命令参考：https://docs.astral.sh/uv/reference/cli/
GitHub：https://github.com/astral-sh/uv

29. 一句话总结

传统 Python：

text
安装 Python
→ 创建 venv
→ 激活环境
→ pip install
→ requirements.txt
→ python main.py

使用 uv：

text
uv python install
→ uv init
→ uv add
→ uv sync
→ uv run

对于新项目，可以把 uv 理解成：

Python 版本管理 + 虚拟环境 + pip + requirements/lock + 项目运行工具的一体化方案。

目录

uv