What causes "You can only add optional dependencies to the main group" in python-poetry/poetry?

Remove the -G/--dev flag so the dependency is added to the main group, which is required for --optional.

python-poetry/poetry · error · ValueError

You can only add optional dependencies to the main group

Error message

You can only add optional dependencies to the main group

What it means

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`.

Source

Thrown at src/poetry/console/commands/add.py:148

        from tomlkit import nl
        from tomlkit import table

        from poetry.factory import Factory

        packages = self.argument("name")
        if self.option("dev"):
            group = "dev"
        else:
            group = self.option("group", self.default_group or MAIN_GROUP)

        if self.option("extras") and len(packages) > 1:
            raise ValueError(
                "You can only specify one package when using the --extras option"
            )

        optional = self.option("optional")
        if optional and group != MAIN_GROUP:
            raise ValueError("You can only add optional dependencies to the main group")

        content = self.poetry.file.read()
        project_content = content.get("project", table())
        poetry_content = content.get("tool", {}).get("poetry", table())
        groups_content = content.get("dependency-groups", {})
        project_name = (
            canonicalize_name(name)
            if (name := project_content.get("name", poetry_content.get("name")))
            else None
        )

        use_project_section = False
        use_groups_section = False
        project_dependency_names: list[NormalizedName | Literal["<include-group>"]] = []

        # Run-Time Deps incl. extras
        if group == MAIN_GROUP:
            if (

View on GitHub (pinned to 92b74dcfe3)

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.

Example fix

# before (error)
poetry add --optional security requests -G dev
# after
poetry add --optional security requests

Defensive patterns

Strategy: validation

Validate before calling

from poetry.core.packages.dependency_group import MAIN_GROUP

def validate_optional(optional, group: str) -> None:
    if optional and group != MAIN_GROUP:
        raise ValueError(
            "--optional can only be used with the main group (no -G/--dev)."
        )

Type guard

from poetry.core.packages.dependency_group import MAIN_GROUP

def can_use_optional(optional, group: str) -> bool:
    return not optional or group == MAIN_GROUP

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of python-poetry/poetry@92b74dcfe3 (2026-08-04). Data as JSON: /data/errors/ed6e17cfe13ac7f6.json. Report an issue: GitHub.