python-poetry/poetry · error · ValueError

You can only specify one package when using the --extras opt

Error message

You can only specify one package when using the --extras option

What it means

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.

Source

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

    ]

    def handle(self) -> int:
        from poetry.core.constraints.version import parse_constraint
        from tomlkit import array
        from tomlkit import inline_table
        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

View on GitHub (pinned to 92b74dcfe3)

Solutions

1. Run separate `poetry add` commands: one with --extras for the package that needs extras, and one or more without for the other packages.
2. If only one package needs extras, remove the extra packages from the command line and add them separately.

Example fix

# before (error)
poetry add requests flask -E security
# after
poetry add requests -E security
poetry add flask

def validate_add_extras(packages: list[str], extras) -> None:
    if extras and len(packages) > 1:
        raise ValueError(
            "--extras can only be used with a single package; "
            "run separate 'poetry add' commands."
        )

def can_use_extras(packages: list[str], extras) -> bool:
    return not extras or len(packages) <= 1

When it happens

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

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

Related errors

• You can only add optional dependencies to the main group
• Invalid config setting format: {config_setting}. Config sett
• Invalid cache key
• You cannot remove the [repositories] section
• You must pass the url. Example: poetry config repositories.f

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