{"id":"1d9570463b732051","repo":"python-poetry/poetry","slug":"you-can-only-specify-one-package-when-using-the","errorCode":null,"errorMessage":"You can only specify one package when using the --extras option","messagePattern":"You can only specify one package when using the --extras option","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/poetry/console/commands/add.py","lineNumber":142,"sourceCode":"    ]\n\n    def handle(self) -> int:\n        from poetry.core.constraints.version import parse_constraint\n        from tomlkit import array\n        from tomlkit import inline_table\n        from tomlkit import nl\n        from tomlkit import table\n\n        from poetry.factory import Factory\n\n        packages = self.argument(\"name\")\n        if self.option(\"dev\"):\n            group = \"dev\"\n        else:\n            group = self.option(\"group\", self.default_group or MAIN_GROUP)\n\n        if self.option(\"extras\") and len(packages) > 1:\n            raise ValueError(\n                \"You can only specify one package when using the --extras option\"\n            )\n\n        optional = self.option(\"optional\")\n        if optional and group != MAIN_GROUP:\n            raise ValueError(\"You can only add optional dependencies to the main group\")\n\n        content = self.poetry.file.read()\n        project_content = content.get(\"project\", table())\n        poetry_content = content.get(\"tool\", {}).get(\"poetry\", table())\n        groups_content = content.get(\"dependency-groups\", {})\n        project_name = (\n            canonicalize_name(name)\n            if (name := project_content.get(\"name\", poetry_content.get(\"name\")))\n            else None\n        )\n\n        use_project_section = False","sourceCodeStart":124,"sourceCodeEnd":160,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/console/commands/add.py#L124-L160","documentation":"Raises ValueError in AddCommand.handle() when the --extras (-E) option is used together with more than one package argument. The constraint exists because extras apply to a single dependency; applying extras to multiple packages simultaneously would be ambiguous. The check fires at line 141-144 before any dependency resolution begins.","triggerScenarios":"Running `poetry add pkg-a pkg-b -E extra1` — passing two or more package names while also specifying --extras. The check is `if self.option('extras') and len(packages) > 1`.","commonSituations":"User intends to install multiple packages with extras for one of them but passes them all in a single command. Or user misunderstands --extras as applying per-package rather than globally to the single add operation.","solutions":["Run separate `poetry add` commands: one with --extras for the package that needs extras, and one or more without for the other packages.","If only one package needs extras, remove the extra packages from the command line and add them separately."],"exampleFix":"# before (error)\npoetry add requests flask -E security\n# after\npoetry add requests -E security\npoetry add flask","handlingStrategy":"validation","validationCode":"def validate_add_extras(packages: list[str], extras) -> None:\n    if extras and len(packages) > 1:\n        raise ValueError(\n            \"--extras can only be used with a single package; \"\n            \"run separate 'poetry add' commands.\"\n        )","typeGuard":"def can_use_extras(packages: list[str], extras) -> bool:\n    return not extras or len(packages) <= 1","tryCatchPattern":null,"preventionTips":["Limit --extras usage to a single package per 'poetry add' invocation.","Split multi-package adds into separate commands when one package needs extras.","Remember --extras applies to the single dependency being added, not globally."],"tags":["add-command","extras","valueerror","cli-validation"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}