rye add 命令详解:用 PEP 508 与辅助参数为 Python 项目添加依赖
rye add 命令详解:用 PEP 508 与辅助参数为 Python 项目添加依赖
本篇指南聚焦 Rye 项目(a Hassle-Free Python Experience)中的 rye add 命令,系统讲解如何通过 PEP 508 需求字符串为当前项目声明、解析并安装 Python 依赖,覆盖 git / URL / 本地路径依赖、extras 特性、dev 与 optional 依赖分组、pin 操作符控制以及自动同步机制。读完本文,你将掌握 rye add 的完整用法与底层执行流程,能够在不手动编辑 pyproject.toml 的情况下准确、可控地管理项目依赖。
命令概览:rye add
rye add 用于将一个 Python 包添加到当前项目。它接受 PEP 508 需求字符串(例如 'flask==2.2.3')作为输入,同时提供一组辅助参数来简化操作。例如,你不需要把 git 引用写进需求字符串里,直接使用 --git 参数即可完成 git 依赖的添加。
添加依赖之后的行为取决于 auto-sync(自动同步) 配置:
- 如果自动同步被禁用,依赖不会自动安装,需要手动执行
rye sync或在本命令中显式传入--sync; - 如果要移除依赖,使用
rye remove命令。
版本说明:自 0.26.0 起,
rye add增加了自动同步支持,以及--sync/--no-sync两个显式控制参数。
典型用法示例
添加与当前 Python 版本兼容的最新版本
$ rye add flask
Added flask>=3.0.1 as regular dependency
这里 rye 会先用项目配置的 Python 版本向索引源查询最新可用版本,再把版本信息以 >= 形式写回依赖声明(具体的运算符默认值与改写规则见后文「pin 操作符与默认运算符」)。
添加依赖并附带可选特性(extras)
$ rye add flask --features dotenv
Added flask[dotenv]>=3.0.1 as regular dependency
--features 会把特性写入需求中的 extras 部分,最终以 flask<a href="https://link.gitcode.com/i/94a222b1643b3fba75a1a16c9d513e03" target="_blank">dotenv] 的形式出现在 pyproject.toml 的依赖列表中。--features 支持多个值,也支持用逗号分隔多个特性,且自动去重(见 [add.rs 的 extras 处理逻辑)。
添加 git 依赖
$ rye add flask --git https://github.com/pallets/flask
Added flask @ git+https://github.com/pallets/flask as regular dependency
底层实现会把 --git 与可选的 --tag / --rev / --branch 组合成 git+<url>@<ref> 形式的 URL 写进依赖(见 add.rs)。
添加本地路径依赖
$ rye add packagename --path path/to/packagename
Added packagename @ file:///path/to/packagename as regular dependency
本地路径依赖会被转换为 file:// URL 写入依赖声明。关于相对路径与绝对路径的处理细节,见后文「本地路径依赖的路径解析」。
参数(Arguments)
<REQUIREMENTS>...:要添加的包,以 PEP 508 需求字符串形式给出,例如'flask==2.2.3'。支持一次传入多个需求字符串,但有一个例外:一旦使用了--git/--url/--path/--features这类"针对单个需求"的辅助参数,就必须只传一个需求,否则命令会直接报错退出(见 add.rs 的校验逻辑)。
选项(Options)
| 选项 | 说明 | 源码约束(来自 add.rs) |
|---|---|---|
--git <GIT> |
从指定的 git 仓库安装该包 | 可与 --tag/--rev/--branch 组合;与 --url、--path 互斥 |
--url <URL> |
从指定的 URL 安装该包 | 与 --git、--path 互斥 |
--path <PATH> |
从指定的本地路径安装该包 | 与 --git、--url 互斥 |
--absolute |
强制使用非插值的绝对路径 | 依赖 --path(即必须与 --path 同时使用) |
--tag <TAG> |
安装指定 tag | 依赖 --git |
--rev <REV> |
更新到指定 git rev | 依赖 --git;与 --tag、--branch 互斥 |
--branch <BRANCH> |
更新到指定 git branch | 依赖 --git;与 --tag、--rev 互斥 |
--features <FEATURES> |
以特定 feature(extras)添加依赖 | 可重复使用;多个特性之间也可用逗号分隔 |
--dev |
将依赖添加为 dev 依赖 | 源码中注册了短选项 -d;与 --excluded、--optional 互斥 |
--excluded |
添加为 excluded 依赖:即使它是其他包的子依赖也不会被安装 | 与 --dev、--optional 互斥 |
--optional <OPTIONAL> |
将依赖添加到某个可选依赖组 | 与 --dev、--excluded 互斥 |
--pre |
解析包版本时允许使用预发布版本 | — |
--pin <PIN> |
覆盖默认的 pin 运算符 | 可选值:equal、tilde-equal、greater-than-equal(详见下文别名) |
--sync |
即使禁用了 auto-sync 也自动执行 sync |
与 --no-sync 互斥 |
--no-sync |
即使启用了 auto-sync 也不执行 sync |
与 --sync 互斥 |
-v, --verbose |
开启详细诊断输出 | 与 --quiet 互斥 |
-q, --quiet |
关闭所有输出 | 与 --verbose 互斥 |
-h, --help |
打印帮助信息(-h 显示摘要) |
clap 自动生成 |
源码中还额外提供了一组与锁定行为相关的选项(未在命令文档中单独列出,但存在于 add.rs 的参数定义中):--with-sources(在 lockfile 中记录来源)、--generate-hashes(在 lockfile 中生成哈希)、--keyring-provider <KEYRING_PROVIDER>(为索引 URL 尝试使用 keyring 认证)。它们会在自动同步 workspace 时生效。
--pin 的取值与别名
--pin 选项在源码中定义为一个枚举 Pin(见 add.rs),三个标准值各自带有若干别名:
equal(别名:exact、==、eq)→ 对应运算符==tilde-equal(别名:tilde、compatible、~=)→ 对应运算符~=greater-than-equal(别名:>=、ge、gte)→ 对应运算符>=
依赖类型与它们在 pyproject.toml 中的位置
rye add 支持四种依赖类型,由源码中的 DependencyKind 枚举描述(见 pyproject.rs):
| 类型 | 触发方式 | 写入位置(见 pyproject.rs) |
|---|---|---|
| regular(常规) | 默认 | [project] dependencies |
| dev(开发) | --dev |
[tool.rye] dev-dependencies |
| excluded(排除) | --excluded |
[tool.rye] excluded-dependencies |
| optional(可选组) | --optional <section> |
[project] optional-dependencies.<section> |
命令完成时的输出会带上依赖类型,例如文档与测试快照中出现的 Added flask>=3.0.1 as regular dependency、Added flask as dev dependency,以及可选依赖的 Added ... as optional (section) dependency(DependencyKind 的 Display 实现见 pyproject.rs)。
添加完成后,pyproject.toml 中会出现类似下面的内容:
[project]
dependencies = [
"flask>=3.0.1",
"flask[dotenv]>=3.0.1",
"flask @ git+https://github.com/pallets/flask",
"packagename @ file:///path/to/packagename",
]
optional-dependencies = { test = ["pytest>=8.0.0"] }
[tool.rye]
dev-dependencies = ["pytest>=8.0.0"]
excluded-dependencies = ["some-transitive-dep"]
底层执行流程:add 命令内部做了什么
rye add 的实际执行逻辑位于 add.rs 的 execute 函数,整体流程如下:
- 引导自身虚拟环境:调用
ensure_self_venv确保 rye 自带的工具环境可用; - 发现项目:通过
PyProject::discover()从当前目录向上查找pyproject.toml,并读取项目期望的 venv Python 版本(venv_python_version,见 pyproject.rs); - 确定依赖类型:根据
--dev/--excluded/--optional的优先级确定DependencyKind; - 确定默认运算符:若传了
--pin则使用该值,否则回退到配置default.dependency-operator(见下文); - 解析需求字符串:将每个
<REQUIREMENTS>用pep508_rs的Requirement::from_str解析,随后把--git/--url/--path/--features通过apply_to_requirement应用到需求上(见 add.rs); - 解析版本并落盘:对非 excluded 依赖,先执行一次"仅 Python"的预同步(
sync ahead of add)确保 venv 就绪,再用内部集成的 uv 解析每个需求的真实版本,将解析结果合并回需求对象,最后调用pyproject_toml.add_dependency写入 TOML 并保存; - 输出结果:逐条打印
Added <requirement> as <kind> dependency; - 自动同步:按
(配置了 autosync 且未传 --no-sync) || 传了 --sync的判定条件执行autosync(见 add.rs),其行为包括更新requirements.lock/requirements-dev.lock并安装依赖,详见rye sync与 Syncing and Locking。
版本解析与运算符改写
解析阶段(resolve_requirements_with_uv,见 add.rs)有几个值得注意的细节:
- 若需求本身已带版本或 URL,则保留原有信息,只对包名做规范化;
- 由 uv 解析出的版本说明符会被重写为默认运算符(来自
--pin或配置),其中有两个特例:本地版本(local version)一律使用==;~=应用于主版本号少于两位的版本时会退化为>=。
已带版本约束时的行为
如果需求字符串里已经写了版本标记(例如 werkzeug==3.0.0),再同时使用 --git / --url / --path 会直接报错 "requirement already has a version marker"(见 add.rs)。测试 test_add.rs 中的快照验证了 rye add werkZeug==3.0.0 会保留原版本约束并输出 Added werkzeug==3.0.0 as regular dependency。
pin 操作符与默认运算符配置
如果不显式传 --pin,rye add 使用的默认运算符来自配置键 default.dependency-operator(源码同时兼容旧版拼写 dependency_operator),见 config.rs:
[tool.rye]
default = { dependency-operator = ">=" }
支持的取值及对应运算符为:"==" → Equal,"~=" → TildeEqual,">=" → GreaterThanEqual;未配置或配置了未知值时默认 >=。例如在测试快照中,不指定 --pin 时添加 werkzeug==3.0.0 会保留显式的 == 约束,而添加未固定版本的 flask 则会被解析为 flask>=3.0.1。
本地路径依赖的路径解析
--path 的处理逻辑比较特殊(见 add.rs),取决于两个因素:
- 构建后端:如果项目使用 hatchling 构建后端,由于 hatchling 的
{root:uri}相对路径写法不被 uv 支持,而${PROJECT_ROOT}又会在 hatchling 中报错,因此会强制使用绝对路径(file://形式的完整路径); --absolute参数:显式传入--absolute时同样强制生成非插值的绝对路径。
默认情况下(非 hatchling 且未传 --absolute),生成的路径是相对于当前目录的 file:///${PROJECT_ROOT}/<相对路径> 形式,其中 ${PROJECT_ROOT} 在后续同步阶段被插值为实际项目根目录。
测试验证与输出示例
仓库中的集成测试 test_add.rs 覆盖了本文涉及的多种场景:test_add_flask(基础添加)、test_add_flask_dotenv(extras 特性)、test_add_dev(--dev 多包添加)、test_add_explicit_version_or_url(显式版本与 URL 依赖)、test_add_from_find_links 等。典型输出如下:
Added werkzeug==3.0.0 as regular dependency
Reusing already existing virtualenv
Generating production lockfile: .../requirements.lock
Generating dev lockfile: .../requirements-dev.lock
Installing dependencies
Resolved 3 packages in ...
Prepared 3 packages in ...
Installed 3 packages in ...
+ werkzeug==3.0.0
+ markupsafe==2.1.3
+ my-project==0.1.0 (from file:...)
可以看到,rye add 不是简单地把字符串写进 TOML,而是完整走完"解析 → 解析版本 → 写入声明 → 生成 lockfile → 安装"的闭环。结合 rye remove 与 rye sync,你可以在完全不手写 pyproject.toml 的情况下,完成项目依赖的增删与锁定。