wbroom

如何使用 uv（Astral）：安裝 uv、uv init、uv add、uv run 與 pip/venv 對照

以 uv init、uv add 管理 Python 專案，uv run 取代手動啟用 venv。

新建 Python 小项目时，常见路径是 python -m venv、手写 requirements.txt、每次跑脚本前还要 source 激活。uv（Astral / Ruff 团队）把项目当成现代包管理器来管：uv init 生成 pyproject.toml，uv add 写依赖并更新锁文件，uv run 在项目环境里执行脚本，往往不必再手动 activate。

搜尋 uv 安裝 uv init uv add 跑脚本 对比 pip venv 的人，通常要完成：安裝 uv CLI、uv init 建项目、uv add 加依赖、uv run 跑入口，并理解相对传统 pip + venv 的差异。步骤以 docs.astral.sh/uv 为准。

安裝 uvuv init · uv adduv run · 對照 pip/venv

项目工作流适合谁

01

新脚本与小服务

uv init 加 uv add httpx 几分钟内得到带锁文件的仓库，不必先单独建 venv 再 import。

02

笔记本与 CI 老对不上的团队

uv.lock 与 uv sync 让安裝可复现；CI 与本地用同一套解析结果。

03

从 pip/venv 渐进迁移的人

旧仓库可继续 .venv + uv pip — 见本站 uv venv 与 uv pip 指南；全新项目更适合 uv init。

安裝 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 下载并 pin 解释器（见文档 Python versions）。

用 uv init 建立项目

  1. 1

    空目录初始化

    mkdir demo-api && cd demo-api，运行 uv init。会写入 pyproject.toml、示例模块或应用结构，常见还有 .python-version（具体文件随模板与 flags 变化，以 uv init --help 为准）。

  2. 2

    非交互

    uv init --name demo-api 等文档中的 library / application 选项；写 CI 前先在本机 -h 核对。

  3. 3

    首次 sync

    uv sync 建立 .venv、按配置可编辑安裝项目，并在有锁文件时装齐依赖。

mkdir demo-api && cd demo-api
uv init
uv sync
uv run python -V

用 uv add 新增依赖

  1. 1

    运行时依赖

    uv add httpx 更新 pyproject.toml、刷新 uv.lock，并装进项目环境。

  2. 2

    仅开发工具

    uv add --dev pytest ruff（flag 以文档为准），配合 dependency groups 避免把测试/ lint 工具打进生产安裝。

  3. 3

    移除或升级

    uv remove pkg、uv lock --upgrade-package pkg 等子命令见 uv add -h。

相对 pip，不必每台机器手改 requirements.txt 再各自 resolve：uv add 之后以锁文件为共享真相源。

用 uv run 跑脚本

目标pip + venv 习惯uv 项目习惯
初始化python -m venv .venv + 激活uv init + uv sync
加库pip install pkg 再 freezeuv add pkg
跑应用激活后 python main.pyuv run python main.py
跑工具全局 pipx 或单独 venvuv run pytest 或 uv run --with ruff ruff check .
CI 安裝pip install -r requirements.txtuv sync --frozen
  1. 1

    项目入口

    uv run python main.py 或 pyproject.toml 里声明的 console script — uv 自动选项目解释器。

  2. 2

    一次性工具

    uv run --with ruff ruff check . 在隔离环境拉工具，不污染全局 site-packages（见文档 Running scripts）。

  3. 3

    可不再手动 activate

    很多团队不再 source .venv/bin/activate；若仍激活，行为应一致 — 用 which python 核对。

uv init / uv add 加速的是项目脚手架与锁定安裝；生产容器里仍要在 Dockerfile 明确 Python 基础镜像版本 — uv 不替代这一层。

结对过 pyproject.toml 或 CI 时，可从 wbroom 首页 开浏览器房间 — 建立与加入房间。仍用 requirements.txt 的旧仓库见 uv venv 与 uv pip。

还想核对的问题

还需要 python -m venv 吗？

新项目不必：uv sync 会管 .venv。旧仓库可继续手动 venv + uv pip，再逐步迁到 pyproject.toml。

已有 requirements.txt 能导入吗？

文档有从 requirements 迁入项目的流程 — 在分支上试官方 import/sync，再删旧文件。

能和 Poetry / pip-tools 并存吗？

每个仓库只选一种锁文件故事。Poetry lock 与 uv.lock 混用会 drift；切换时在 README 写清「uv project」。

CI 怎么写？

job 里安裝 uv（install.sh 或官方 Action），uv sync --frozen，再 uv run pytest。日志勿打印私有索引令牌。

開始一場會議