Poetry 依赖组怎么选可选组与 --with、--without、--only 安装控制【免费下载链接】poetryPython packaging and dependency management made easy项目地址: https://gitcode.com/GitHub_Trending/po/poetry一个 Poetry 项目的pyproject.toml里通常只有几个运行期依赖而测试、文档构建等工具只在开发阶段需要。把它们全部写进主依赖会拖慢安装和部署用依赖组dependency groups把它们分开后就能通过poetry install的--with、--without、--only参数精确控制每次安装哪些组。本文基于官方文档 Managing dependencies 与 CLI 参考说明如何声明分组、如何为不同安装场景选参数以及安装后如何验证结果。在 pyproject.toml 中声明依赖组project.dependenciesPEP 621或tool.poetry.dependencies中声明的依赖属于隐式的main组这些是项目运行期必需的依赖。除此之外的依赖可以按用途声明为新的组。文档提供两种写法# PEP 735 的 dependency-groups 写法 [dependency-groups] test [ pytest (6.0.0,7.0.0), pytest-mock, ]# tool.poetry 写法组名为 test [tool.poetry.group.test.dependencies] pytest ^6.0.0 pytest-mock *组名test、docs、dev等由你自己定上面的包名来自文档示例可按实际需要替换。两条来自文档的规则需要先记住依赖组本质上是标签。组里的依赖无论是否会被安装都会参与解析因此所有组之间的依赖必须彼此兼容否则解析会失败。除隐式main组外的组只应包含开发过程需要的依赖。运行期为项目增加功能的依赖应改用 extras见 pyproject.md 的 extras 一节。向组中添加和移除依赖用add命令的--group简写-G选项把依赖加进指定组组不存在时会自动创建poetry add pytest --group test从指定组移除包时remove命令支持同样的--group选项poetry remove mkdocs --group docs可选组只有显式要求才安装的分组如果一组依赖只在特定环境或特定用途下才需要例如文档构建工具可以把它声明为可选组optional[tool.poetry.group.docs] optional true [tool.poetry.group.docs.dependencies] mkdocs *PEP 735 写法下组依赖写在[dependency-groups]可选标记仍写在tool.poetry.group.group表中[dependency-groups] docs [ mkdocs, ] [tool.poetry.group.docs] optional true可选组默认不会被安装用--with在默认依赖之外额外安装poetry install --with docs注意可选组的依赖同样会参与解析所以声明时就要确保它们与项目中其他依赖兼容。用 include-groups 聚合多个组当你想用一个组名一次性拉起多个组时可以用include-groupPEP 735或include-groupstool.poetry[dependency-groups] test [ pytest (8.0.0,9.0.0), ] lint [ ruff (0.11.0,0.12.0), ] dev [ { include-group test }, { include-group lint }, tox, ][tool.poetry.group.test.dependencies] pytest ^8.0.0 [tool.poetry.group.lint.dependencies] ruff ^0.11 [tool.poetry.group.dev] include-groups [ test, lint, ] [tool.poetry.group.dev.dependencies] tox *文档给出的例子中dev组因此包含了test与lint两个组的全部依赖再加dev组自己的tox。安装时如何选参数默认行为poetry install会安装所有非可选组的依赖即隐式main组加上所有未标记optional true的组。在此之上按场景选择参数排除组 ——--without。把不需要的一组或多组排除掉组名之间用逗号分隔poetry install --without test,docs启用可选组 ——--with。可选组默认不装用--with额外纳入poetry install --with docs两者同时出现时--without优先于--with。文档给出的例子poetry install --with test,docs --without docs该命令最终只安装可选test组中声明的依赖。只装指定组 ——--only。不安装默认依赖集合只装点名的组poetry install --only docs两个常用特例# 只安装项目的运行期依赖隐式 main 组 poetry install --only main # 只安装项目根本身不安装任何依赖 poetry install --only-root指定--only时--with和--without选项会被忽略install、sync、update、show均适用这条规则。装全部组 ——--all-groups。包括可选组在内的所有组全部安装该标志与--only、--with、--without互斥不能组合使用poetry install --all-groups同一个项目该用 install 还是 syncCLI 文档 对两条路径的分工写得很明确poetry install读取pyproject.toml解析并安装依赖存在poetry.lock时按锁文件中的精确版本安装没有锁文件则解析后创建。它是你克隆项目后跑的命令。可复现安装更推荐poetry sync它与install行为类似但会额外移除不在锁文件中跟踪的包避免环境里残留未跟踪的过期包。例外是当你设置了virtualenvs.create false装进系统环境文档不推荐或virtualenvs.options.system-site-packages true时应使用poetry install因为sync在这些情况下通常不适用。三条命令支持同一套组选项poetry sync--without、--with、--only、--only-root、--all-groups例如poetry sync --without dev、poetry sync --only dev。poetry install除上述选项外还有一个已废弃的--sync文档提示改用poetry sync。poetry update支持--without、--with、--only用于在约束内刷新依赖版本并更新poetry.lock。poetry update不修改pyproject.toml只按已有约束更新锁文件要改版本约束应使用add。还有一个针对多阶段 Docker 构建的行为不带--sync选项的poetry install可以在不卸载已安装可选组的前提下再安装任意子集的可选组适合在多个构建阶段反复执行poetry install的场景。反过来poetry sync会把环境严格同步到锁文件和所选组extras 与组是相互独立的未被选中的 extras 总是会被移除。验证安装结果先预览再执行。--dry-run只输出将要执行的操作而不实际执行隐式启用--verboseinstall、sync、update都支持poetry install --only docs --dry-run核对包清单。poetry show同样支持--with、--without、--only选项可以用同样的组选择查看对应会包含哪些包例如poetry show --only test。它还提供--why显示包是直接依赖还是被其他包要求、--tree树形展示依赖、--top-level只看显式声明的包等选项。确认环境。安装完成后用poetry env info查看当前虚拟环境的 Python 版本、路径与有效性见 Managing environments。文档中的安装输出示例其中your-package-name(x.x.x) 是文档占位写法$ poetry install Installing dependencies from lock file No dependencies to install or update - Installing your-package-name (x.x.x)这个示例同时说明一点默认每次运行install都会重新安装项目自身的包。想跳过根包安装用--no-root--no-directory可跳过目录路径依赖含传递依赖文档说明它主要用于 CI 缓存或构建 Docker 镜像时。限制与边界所有组一起解析即使某组不会被安装它的依赖也参与解析。组间依赖不兼容时解析阶段就会失败与安装参数无关。组的定位是开发期组织非main组只放开发过程依赖运行期功能扩展用 extras。install 不会“反向清理”默认poetry install只装所选集合不会移除环境中已有的其他包需要环境严格匹配锁文件与所选组时用poetry sync。参数互斥关系--all-groups与--only/--with/--without互斥指定--only后--with/--without被忽略。完成一次分组改造后的典型流程是在pyproject.toml中声明组必要时标optional true→poetry lock刷新锁文件 → 用--dry-run预览组选择的效果 → 正式执行poetry install或poetry sync→ 用poetry show核对包清单。【免费下载链接】poetryPython packaging and dependency management made easy项目地址: https://gitcode.com/GitHub_Trending/po/poetry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
