{"id":"ed6e17cfe13ac7f6","repo":"python-poetry/poetry","slug":"you-can-only-add-optional-dependencies-to-the-main","errorCode":null,"errorMessage":"You can only add optional dependencies to the main group","messagePattern":"You can only add optional dependencies to the main group","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/poetry/console/commands/add.py","lineNumber":148,"sourceCode":"        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\n        use_groups_section = False\n        project_dependency_names: list[NormalizedName | Literal[\"<include-group>\"]] = []\n\n        # Run-Time Deps incl. extras\n        if group == MAIN_GROUP:\n            if (","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/python-poetry/poetry/blob/92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54/src/poetry/console/commands/add.py#L130-L166","documentation":"Raises ValueError in AddCommand.handle() when the --optional option is combined with a dependency group other than the main group. Optional dependencies (extras) are a concept tied to the main dependency group in Poetry's data model; adding them to a non-main group is semantically invalid. The check at line 147 reads `if optional and group != MAIN_GROUP`.","triggerScenarios":"Running `poetry add --optional my-extra pkg -G dev` or `poetry add --optional my-extra pkg --dev`, i.e. specifying --optional together with -G/--dev so the target group is not the main group.","commonSituations":"User wants to create an extra but mistakenly targets a dev or custom group. User misunderstands that optional/extras are only valid in the main dependency section.","solutions":["Remove the -G/--dev flag so the dependency is added to the main group, which is required for --optional.","If the dependency genuinely belongs in a non-main group, drop --optional and add it as a regular group dependency."],"exampleFix":"# before (error)\npoetry add --optional security requests -G dev\n# after\npoetry add --optional security requests","handlingStrategy":"validation","validationCode":"from poetry.core.packages.dependency_group import MAIN_GROUP\n\ndef validate_optional(optional, group: str) -> None:\n    if optional and group != MAIN_GROUP:\n        raise ValueError(\n            \"--optional can only be used with the main group (no -G/--dev).\"\n        )","typeGuard":"from poetry.core.packages.dependency_group import MAIN_GROUP\n\ndef can_use_optional(optional, group: str) -> bool:\n    return not optional or group == MAIN_GROUP","tryCatchPattern":null,"preventionTips":["Never combine --optional with -G or --dev; optional dependencies must go in the main group.","Understand that extras/optional-dependencies are a main-group-only concept in PEP 621 and Poetry.","Use dependency groups for non-main dependencies instead of --optional."],"tags":["add-command","optional-dependencies","extras","dependency-groups","valueerror"],"analyzedSha":"92b74dcfe348d0e01e14d40d6c1fa47a4ee04a54","analyzedAt":"2026-08-04T20:33:34.072Z","schemaVersion":2}