wbroom

如何使用 uv Python 包管理器：安装 uv、创建 venv、uv pip 与更快跑脚本

装好 uv，用 venv + uv pip + uv run 把 Python 依赖和脚本跑得比传统 pip 更顺。

新建 Python 项目时，python -m venv 再 pip install 往往慢、缓存乱、CI 与笔记本还不一致。uv 是 Astral（Ruff 同团队）用 Rust 写的 Python 包与环境工具：装解释器、建 venv、用 uv pip 装依赖，通常比传统 pip 快一个数量级。

搜索 uv Python 包管理器 安装 venv pip install 跑脚本 的人，通常要完成：安装 uv CLI、uv venv 建虚拟环境、uv pip install 装包、uv run 在项目环境里跑脚本。步骤以官方文档 docs.astral.sh/uv 为准。

安装 uvuv venv · 激活uv pip · uv run

uv 适合谁

01

每天要开很多 Python 仓库的人

uv venv 秒级创建 .venv；uv pip install -r requirements.txt 比反复调 pip 镜像更省心。

02

想统一笔记本与 CI 的团队

uv.lock + uv sync（有 pyproject.toml 时）让依赖可 diff；纯 requirements 阶段也能先用 uv pip。

03

从 pip/poetry 迁移但不想立刻大改的人

uv 提供 pip 兼容子命令，不必第一天就重写构建系统。

安装 uv（macOS / Linux）

  1. 1

    官方安装脚本（推荐）

    在终端执行文档 Getting Started 中的命令，例如 curl -LsSf https://astral.sh/uv/install.sh | sh。装完后新开终端，运行 uv --version。

  2. 2

    macOS：Homebrew

    brew install uv 同样官方支持。只选一种安装方式，避免 PATH 里多个 uv 二进制。

  3. 3

    Linux / WSL

    优先用 install.sh；部分发行版可能有社区包。验证：which uv 与 uv --version。

  4. 4

    可选：固定 Python 版本

    uv python install 3.12 让 uv 下载并管理解释器（见文档 Python versions 章节），不必依赖系统自带旧 Python。

创建并激活虚拟环境

  1. 1

    在项目根建 venv

    cd your-project 后运行 uv venv，默认创建 .venv。指定版本：uv venv --python 3.12。

  2. 2

    激活（可选）

    macOS/Linux：source .venv/bin/activate。若全程用 uv run / uv pip 且带 --python .venv 或已在项目目录，有时可不手动 activate — 以文档为准。

  3. 3

    确认解释器

    uv run python -V 或激活后 which python 应指向 .venv。

用 uv pip 安装依赖

在已激活的 venv 或项目目录中：

# 单个包
uv pip install httpx

# requirements 文件
uv pip install -r requirements.txt

# 可编辑安装本地包
uv pip install -e .

uv 使用全局缓存与并行解析，重复安装同一版本时通常明显快于裸 pip。私有索引按文档设置 UV_INDEX_URL 或 pip 兼容配置。

用 uv run 更快跑脚本

  1. 1

    直接跑模块或脚本

    uv run python main.py 或 uv run pytest — uv 会选用项目虚拟环境（存在 .venv 或 pyproject.toml 时）。

  2. 2

    临时工具（无全局污染）

    uv run --with ruff ruff check . 按文档在隔离环境拉一次性工具（见 Running scripts）。

  3. 3

    有 pyproject 时用 sync

    uv sync 根据锁文件安装全部依赖，再 uv run … — 适合长期项目。

任务pip 习惯uv 对应
建 venvpython -m venv .venvuv venv
装包pip install pkguv pip install pkg
跑命令activate 后 python app.pyuv run python app.py

uv 加速的是本地与 CI 装包、建环境，不替代生产镜像里对 Python 基础镜像的 pin — Docker 里仍应在 Dockerfile 写明版本。

结对排查依赖或远程过一遍 pyproject.toml 时，可从 wbroom 首页 开浏览器房间，见 创建与加入房间。

还想核对的问题

uv 会替换系统 Python 吗？

不会。uv 下载/管理项目用的解释器与虚拟环境；系统 /usr/bin/python3 仍由发行版维护。用 uv python list 看 uv 管理的版本。

已有 requirements.txt，还要 pyproject.toml 吗？

不必立刻迁移。uv pip install -r requirements.txt 在 .venv 里同样可用。想锁版本与 uv sync 时，再逐步加 pyproject.toml 与 uv.lock（见官方 Projects 文档）。

和 pip、poetry、conda 能并存吗？

可以，但同一项目建议只激活一个环境。混用多个工具写同一路径的 venv 容易乱。团队仓库在 README 里写清「用 uv + .venv」即可。

CI 里怎么用 uv？

在 job 里安装 uv（官方 install.sh 或 GitHub Action），uv sync --frozen 或 uv pip install -r requirements.txt，再 uv run pytest。勿在日志打印 UV_INDEX_* 里的私有令牌。

开始一场会议