How should project.optional-dependencies be managed from the CLI?

[dunossauro]

The documentation says that the old [tool.poetry.extras] mechanism is deprecated and recommends using [project.optional-dependencies] instead:

Deprecated: Use project.optional-dependencies instead.

I'm trying to understand what the intended CLI workflow is for managing these optional dependencies after they have been defined.

Environment:

$ poetry --version
Poetry (version 2.4.3)

$ python --version
Python 3.14.7

I created a fresh project:

$ poetry new --flat deps
$ cd deps

Creating an optional dependency

I used the documented --optional option:

$ poetry add --optional cli cleo
Using version ^2.1.0 for cleo

And this create an optional-dependencies

[project]
name = "deps"
version = "0.1.0"
description = ""
authors = [
    {name = "dunossauro",email = "mendesxeduardo@gmail.com"}
]
readme = "README.md"
requires-python = ">=3.14,<4"
dependencies = []

[project.optional-dependencies]
cli = ["cleo (>=2.1.0,<3.0.0)"]

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

This seems correct.

I can also activate the project extra during installation:

$ poetry install -E cli

and cleo is installed.

So far, everything is clear.

What is the CLI workflow after creation?

The problem starts when I want to modify the existing optional dependency group.

For example, I would expect something analogous to:

poetry remove --optional cli cleo

but:

$ poetry remove --optional cli cleo
The option "--optional" does not exist

I also tried:

$ poetry remove -E cli cleo
The option "-E" does not exist

The same applies to update:

$ poetry update --optional cli
The option "--optional" does not exist

$ poetry update -E cli
The option "-E" does not exist

So --optional appears to be available when creating an optional dependency, but there doesn't seem to be a corresponding mechanism for modifying or removing dependencies from an existing [project.optional-dependencies] entry.

What does -E mean in poetry add?

There is another confusing behavior.

Given:

[project.optional-dependencies]
cli = ["cleo (>=2.1.0,<3.0.0)"]

I tried to add rich to the same project extra:

$ poetry add -E cli rich
Using version ^15.0.0 for rich

I initially interpreted -E cli as "add rich to the project's cli optional dependency".

However, Poetry generated:

dependencies = [
    "cleo[cli] (>=2.1.0,<3.0.0)",
    "rich[cli] (>=15.0.0,<16.0.0)"
]

[project.optional-dependencies]
cli = ["cleo (>=2.1.0,<3.0.0)"]

So it appears that -E cli here means the cli extra of the rich package, effectively:

rich = { extras = ["cli"], ... }

rather than the project's:

[project.optional-dependencies]
cli = [...]

This distinction does make sense given the documentation.

The documentation also says that when a project depends on a package with extras, those extras should be expressed on the dependency itself, for example:

[tool.poetry.dependencies]
pandas = {version="^2.2.1", extras=["computation", "performance"]}

So I understand that there are two different concepts here:

• project optional dependencies, defined by [project.optional-dependencies];
• extras provided by dependencies, such as rich[cli].

My confusion is specifically about the first one.

Comparison with dependency groups

I realize that dependency groups and project optional dependencies have different semantics, and I'm not suggesting that they should behave identically.

However, dependency groups have explicit CLI operations for selecting them, such as:

poetry install --with dev
poetry install --only dev

while project extras have:

poetry install -E cli
poetry install --all-extras

The documentation explains how project extras are activated during installation, but I couldn't find an equivalent CLI workflow for modifying the contents of an existing project extra.

For example, if I have:

[project.optional-dependencies]
cli = [
    "cleo",
    "rich",
]

what is the intended Poetry CLI operation to:

• add another dependency to cli;
• remove a dependency from cli;
• update only the dependencies belonging to cli?

Is manually editing [project.optional-dependencies] the intended workflow?

Questions

1. Is poetry add --optional cli cleo intentionally the only add operation for [project.optional-dependencies]?
2. Is there a supported CLI command for adding another dependency to an existing project optional-dependency group?
3. Is there a supported CLI command for removing a dependency from an existing project optional-dependency group?
4. Is there a supported CLI command for updating dependencies associated with a particular project optional-dependency group?
5. Is -E in poetry add intentionally about dependency/package extras (rich[cli]) rather than project extras defined by [project.optional-dependencies]?
6. If there is no CLI operation for modifying an existing [project.optional-dependencies] entry, is manually editing pyproject.toml the intended workflow?

I'm mainly trying to understand the intended CLI interface now that [tool.poetry.extras] is deprecated in favor of [project.optional-dependencies].

[CAOShurong]

The short answer is that currently, modifying or removing dependencies from [project.optional-dependencies] (or the legacy [tool.poetry.extras]) is intended to be done by editing pyproject.toml directly, followed by poetry lock and poetry install.

Here is the breakdown of why this asymmetry exists, how update behaves, and the cleanest workflow today:

---

1. Why is there no poetry remove --optional?

While poetry add --optional <extra> <package> was implemented to append new optional dependencies to project.optional-dependencies (PEP 621), poetry remove does not yet support an --optional option.

This gap was discussed in Issue #10703 and attempted in PRs #10726 and #10734. The maintainers noted that extras introduce multi-set membership complexities:

• A single package may belong to multiple extras simultaneously (e.g. cli = ["cleo"] and all = ["cleo"]), or to both dependencies and an extra.
• If someone runs poetry remove <pkg>, should it be removed from all extras or fail?
• If an --optional <extra> flag were introduced and the last dependency in an extra is removed, should Poetry delete the whole extra key or preserve an empty list (cli = [])?

Because of these combinatorial edge cases, the current official recommendation from maintainers is to handle removals directly in pyproject.toml.

---

2. How poetry update works with optional dependencies

poetry update operates on package names, not groups or extras:

• You don't need --optional or -E for updates: running poetry update cleo will resolve and update cleo in poetry.lock whether it is declared in dependencies, dependency-groups, or optional-dependencies.
• Running a bare poetry update updates all locked packages across your project.

---

3. Recommended Workflow Today

• Adding an optional dependency:

  poetry add --optional <extra_name> <package>

• Removing an optional dependency:

  1. Open pyproject.toml and remove the package string from [project.optional-dependencies.<extra_name>] (or delete the extra if no longer needed).
  2. Sync poetry.lock and your virtual environment:

     # Re-generate poetry.lock according to pyproject.toml without upgrading other packages:
     poetry lock --no-update
     
     # Synchronize the virtualenv (uninstalls packages no longer referenced):
     poetry install -E <extra_name> --sync

• Updating an optional dependency:

  poetry update <package>

[Lion504]

Adding to an existing extra already works in 2.4.3: repeat --optional cli with the new package. It does not replace the existing contents.

poetry add --optional cli rich

Starting with your cli = ["cleo ..."], this leaves both cleo and rich in project.optional-dependencies.cli and leaves project.dependencies empty.

The remaining operations differ:

• Remove from one extra: edit that extra's array in pyproject.toml, then run poetry lock. In 2.4.3, remove has no --optional selector, and plain poetry remove cleo reports “packages were not found” when cleo is declared only in project.optional-dependencies.
• Update the packages in cli: list their names, e.g. poetry update cleo rich --lock, then poetry sync -E cli to install the selected extra. There is no extra-name selector on update. Shared/transitive dependencies may also change as required by resolution.
• Select an extra provided by a dependency: that is what poetry add -E cli rich means. It adds rich[cli] to the main dependencies; it does not place rich in your project's cli extra. poetry install -E cli instead activates your project's extra.

One version correction to the earlier reply: poetry lock --no-update does not exist in 2.4.3. Use poetry lock; keeping existing locked versions where possible is already the default. After editing an extra, poetry sync -E cli synchronizes the environment with the updated lock file and selected extra. Include any other extras you still want installed.

I verified these cases in a clean temporary project with Poetry 2.4.3/Python 3.13.9, including keeping cleo in a second extra while removing it from cli. Testing and drafting were AI-assisted.

References: add options, lock, update.