uv 可以统一管理 Python 版本、虚拟环境、项目依赖、锁文件和 Python 命令行工具。推荐的职责划分是：

pacman 管理 uv
uv 管理 Python
uv 管理每个项目的虚拟环境与依赖

普通项目不需要手动执行 pip install，也通常不需要激活虚拟环境。日常主要使用 uv init、uv add、uv sync 和 uv run。

安装 uv

Arch Linux 直接从官方仓库安装：

sudo pacman -S uv

确认安装结果：

uv --version

不建议使用 sudo pip install uv，因为这会绕过 pacman 修改系统 Python。pip install uv 虽然可用，但 uv 会依附于当前 Python 环境，不适合作为全局项目管理工具。

创建项目

正式项目可以直接放在 ~/workspace：

cd ~/workspace
uv init network-tools
cd network-tools

基础目录结构：

network-tools/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

第一次添加依赖或同步环境后，还会生成：

.venv/
uv.lock

各文件的职责：

文件	作用	是否提交 Git
pyproject.toml	声明项目元数据和直接依赖	是
uv.lock	锁定完整依赖树的精确版本	是
.python-version	固定项目使用的 Python 版本	建议提交
.venv/	当前机器上的项目虚拟环境	否

管理 Python

安装 Python 3.13：

uv python install 3.13

让当前项目固定使用 Python 3.13：

uv python pin 3.13

查看 uv 能发现或安装的 Python：

uv python list

查看项目实际使用的 Python：

uv run python --version

uv 管理的 Python 与 Arch 系统 Python 相互独立，可以减少系统滚动更新对项目环境的影响。

添加依赖

添加普通依赖：

uv add requests

一次添加多个依赖：

uv add requests pydantic rich

添加开发依赖：

uv add --dev pytest ruff

指定版本范围：

uv add "fastapi>=0.115,<1.0"

添加 Git 仓库中的包：

uv add git+https://github.com/example/project.git

uv add 会同时更新 pyproject.toml、uv.lock 和 .venv。不要再用普通 pip install 修改项目环境，否则实际环境可能与项目声明不一致。

删除依赖

uv remove requests

uv 会自动更新项目声明、锁文件和虚拟环境。

运行项目

运行 Python 文件：

uv run python main.py

运行 Python 模块：

uv run python -m mypackage

运行项目中的工具：

uv run pytest
uv run ruff check .
uv run uvicorn main:app --reload

uv run 会自动使用当前项目的 .venv，并在需要时同步环境，因此一般不必手动激活虚拟环境。

激活虚拟环境

uv run是一种临时运行虚拟环境的方法，如果需要执行多行命令，也可以直接激活虚拟环境，不同终端激活的方式不同。

以arch的Fish终端为例

# cd到项目目录下
source .venv/bin/activate.fish

# 退出环境
deactivate

如果是传统的linux终端，例如bash或者zsh，可以使用如下激活命令

# cd到项目目录下
source .venv/bin/activate

# 退出环境
deactivate

同步环境

根据 pyproject.toml 和 uv.lock 创建或恢复环境：

uv sync

常见使用场景包括：

• 刚克隆项目
• 删除了 .venv
• 切换了 Git 分支
• 拉取到了新的 uv.lock
• 项目依赖发生变化

克隆项目后的标准流程：

git clone <仓库地址>
cd <项目目录>
uv sync
uv run python main.py

严格使用现有锁文件，不允许自动修改：

uv sync --frozen

只安装生产依赖：

uv sync --no-dev

CI 和生产部署更适合使用 uv sync --frozen。

更新依赖

更新锁文件中的全部依赖：

uv lock --upgrade
uv sync

只更新指定依赖：

uv lock --upgrade-package requests
uv sync

如果还要修改项目允许的版本范围，直接重新添加：

uv add "requests>=2.33"

查看依赖

查看完整依赖树：

uv tree

检查锁文件是否需要更新：

uv lock --check

查看项目声明：

cat pyproject.toml

激活虚拟环境

通常直接使用 uv run 即可。需要交互式调试时，Fish 使用：

source .venv/bin/activate.fish

退出虚拟环境：

deactivate

Bash 和 Zsh 使用：

source .venv/bin/activate

迁移旧项目

已有 requirements.txt：

cd ~/workspace/old-project
uv init
uv add -r requirements.txt

如果项目已经包含 pyproject.toml，不需要再次初始化：

cd ~/workspace/old-project
uv sync

临时运行工具

使用 uvx 临时运行工具，不把它加入项目依赖：

uvx ruff check .
uvx black .
uvx httpie

等价写法：

uv tool run ruff check .

如果项目长期依赖某个工具，应把它声明为开发依赖：

uv add --dev ruff
uv run ruff check .

管理全局工具

安装全局 Python 命令行工具：

uv tool install ruff
uv tool install httpie

查看、升级和卸载：

uv tool list
uv tool upgrade ruff
uv tool uninstall ruff

全局工具适合通用 CLI，不应用来安装项目依赖。

Git 提交约定

应该提交：

pyproject.toml
uv.lock
.python-version

不应该提交：

.venv/
__pycache__/
.pytest_cache/
.ruff_cache/

uv init 通常会生成基础 .gitignore，仍应在提交前检查一次。

常用命令

# 创建项目
uv init my-project
cd my-project

# 固定 Python
uv python pin 3.13

# 添加依赖
uv add requests
uv add --dev pytest ruff

# 运行项目与工具
uv run python main.py
uv run pytest
uv run ruff check .

# 删除依赖
uv remove requests

# 恢复环境
uv sync

# 更新依赖
uv lock --upgrade
uv sync

# 查看依赖树
uv tree