feat: Add default-group-optionality configuration option

docs/configuration.md

@@ -611,3 +611,38 @@ for more information.
 Enable the system keyring for storing credentials.
 See [Repositories - Configuring credentials]({{< relref "repositories#configuring-credentials" >}})
 for more information.
+
+### `default-group-optionality`
+
+**Type**: `boolean`
+
+**Default**: `false`
+
+**Environment Variable**: `POETRY_DEFAULT_GROUP_OPTIONALITY`
+
+*Introduced in 2.3.0*
+
+When set to `true`, all dependency groups (except the implicit `main` group) are treated as optional by default.
+This means that `poetry install` will only install the main dependencies unless groups are explicitly requested
+with `--with` or `--only` options.
+
+This setting allows developers to omit the `optional = true` declaration from `pyproject.toml` for most
+dependency groups, reducing configuration verbosity when working with projects that have many optional groups.
+
+{{% note %}}
+This is a user-specific configuration and does not affect the `pyproject.toml` file or how dependencies
+are resolved. It only changes which groups are installed by default.
+{{% /note %}}
+
+**Example usage:**
+
+```bash
+# Enable default-group-optionality
+poetry config default-group-optionality true
+
+# Now only main dependencies are installed by default
+poetry install
+
+# Explicitly include specific groups
+poetry install --with test,docs
+```

src/poetry/config/config.py

@@ -179,6 +179,7 @@ class Config:
         "keyring": {
             "enabled": True,
         },
+        "default-group-optionality": False,
     }
 
     def __init__(self, use_environment: bool = True) -> None:
@@ -389,6 +390,7 @@ def _get_normalizer(name: str) -> Callable[[str], Any]:
             "solver.lazy-wheel",
             "system-git-client",
             "keyring.enabled",
+            "default-group-optionality",
         }:
             return boolean_normalizer
 

src/poetry/console/commands/config.py

@@ -104,6 +104,7 @@ def unique_config_values(self) -> dict[str, tuple[Any, Any]]:
             "solver.lazy-wheel": (boolean_validator, boolean_normalizer),
             "keyring.enabled": (boolean_validator, boolean_normalizer),
             "python.installation-dir": (str, lambda val: str(Path(val))),
+            "default-group-optionality": (boolean_validator, boolean_normalizer),
         }
 
         return unique_config_values

src/poetry/console/commands/group_command.py

@@ -46,6 +46,10 @@ def _group_dependency_options() -> list[Option]:
     @property
     def non_optional_groups(self) -> set[str]:
         # TODO: this should move into poetry-core
+        default_optional = self.poetry.config.get("default-group-optionality", False)
+        if default_optional:
+            # When default-group-optionality is True, all groups are optional
+            return set()
         return {
             group.name
             for group in self.poetry.package._dependency_groups.values()

tests/config/test_config.py

@@ -43,6 +43,7 @@ def get_options_based_on_normalizer(normalizer: Normalizer) -> Iterator[str]:
         ("installer.parallel", True),
         ("virtualenvs.create", True),
         ("requests.max-retries", 0),
+        ("default-group-optionality", False),
     ],
 )
 def test_config_get_default_value(config: Config, name: str, value: bool) -> None:

tests/console/commands/test_config.py

@@ -66,6 +66,7 @@
     venv_path = json.dumps(os.path.join("{cache-dir}", "virtualenvs"))
     expected = f"""cache-dir = {cache_dir}
 data-dir = {data_dir}
+default-group-optionality = false
 installer.max-workers = null
 installer.no-binary = null
 installer.only-binary = null
@@ -101,6 +102,7 @@
     venv_path = json.dumps(os.path.join("{cache-dir}", "virtualenvs"))
     expected = f"""cache-dir = {cache_dir}
 data-dir = {data_dir}
+default-group-optionality = false
 installer.max-workers = null
 installer.no-binary = null
 installer.only-binary = null
@@ -177,7 +179,7 @@
 virtualenvs.use-poetry-python = false
 """
     assert config.set_config_source.call_count == 0  # type: ignore[attr-defined]
     assert tester.io.fetch_output() == expected
 
 
 def test_unset_repo_setting(
@@ -211,7 +213,7 @@
 virtualenvs.use-poetry-python = false
 """
     assert config.set_config_source.call_count == 0  # type: ignore[attr-defined]
     assert tester.io.fetch_output() == expected
 
 
 def test_unset_value_not_exists(tester: CommandTester) -> None:
@@ -347,7 +349,7 @@
 """
 
     assert config.set_config_source.call_count == 1  # type: ignore[attr-defined]
     assert tester.io.fetch_output() == expected
 
 
 def test_list_must_not_display_sources_from_pyproject_toml(
@@ -390,7 +392,7 @@
 virtualenvs.use-poetry-python = false
 """
 
     assert tester.io.fetch_output() == expected
 
 
 def test_set_http_basic(

tests/console/commands/test_default_group_optionality.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from poetry.core.packages.dependency_group import MAIN_GROUP
+
+
+if TYPE_CHECKING:
+    from cleo.testers.command_tester import CommandTester
+    from pytest_mock import MockerFixture
+
+    from poetry.poetry import Poetry
+    from tests.types import CommandTesterFactory
+    from tests.types import ProjectFactory
+
+
+PYPROJECT_CONTENT = """\
+[tool.poetry]
+name = "test-project"
+version = "1.0.0"
+description = "Test project"
+authors = ["Test Author <[email protected]>"]
+
+[tool.poetry.dependencies]
+python = "^3.8"
+requests = "^2.0.0"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^7.0.0"
+
+[tool.poetry.group.dev.dependencies]
+black = "^23.0.0"
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+sphinx = "^5.0.0"
+"""
+
+
+@pytest.fixture
+def poetry(project_factory: ProjectFactory) -> Poetry:
+    return project_factory(
+        name="test-default-group-optionality", pyproject_content=PYPROJECT_CONTENT
+    )
+
+
+@pytest.fixture
+def install_tester(
+    command_tester_factory: CommandTesterFactory, poetry: Poetry
+) -> CommandTester:
+    return command_tester_factory("install")
+
+
+@pytest.fixture
+def config_tester(
+    command_tester_factory: CommandTesterFactory, poetry: Poetry
+) -> CommandTester:
+    return command_tester_factory("config")
+
+
+def test_default_behavior_without_config(
+    install_tester: CommandTester, mocker: MockerFixture
+) -> None:
+    """
+    By default, without the config set, all non-optional groups are installed.
+    """
+    mocker.patch.object(install_tester.command.installer, "run", return_value=0)
+    mocker.patch(
+        "poetry.masonry.builders.editable.EditableBuilder",
+        side_effect=Exception("Should not be called"),
+    )
+
+    status_code = install_tester.execute("--no-root")
+    assert status_code == 0
+
+    # By default, main, test, and dev should be installed (not docs as it's optional)
+    installer_groups = set(install_tester.command.installer._groups or [])
+    assert installer_groups == {MAIN_GROUP, "test", "dev"}
+
+
+def test_with_default_group_optionality_enabled(
+    config_tester: CommandTester,
+    install_tester: CommandTester,
+    mocker: MockerFixture,
+) -> None:
+    """
+    With default-group-optionality enabled, only main group is installed by default.
+    """
+    # Enable the configuration
+    config_tester.execute("--local default-group-optionality true")
+    assert config_tester.status_code == 0
+
+    # Reload config
+    install_tester.command.poetry.config.merge({"default-group-optionality": True})
+
+    mocker.patch.object(install_tester.command.installer, "run", return_value=0)
+    mocker.patch(
+        "poetry.masonry.builders.editable.EditableBuilder",
+        side_effect=Exception("Should not be called"),
+    )
+
+    status_code = install_tester.execute("--no-root")
+    assert status_code == 0
+
+    # With default-group-optionality, only main group should be installed
+    installer_groups = set(install_tester.command.installer._groups or [])
+    assert installer_groups == {MAIN_GROUP}
+
+
+def test_with_default_group_optionality_and_with_option(
+    install_tester: CommandTester, mocker: MockerFixture
+) -> None:
+    """
+    With default-group-optionality enabled, --with can explicitly include groups.
+    """
+    # Enable the configuration
+    install_tester.command.poetry.config.merge({"default-group-optionality": True})
+
+    mocker.patch.object(install_tester.command.installer, "run", return_value=0)
+    mocker.patch(
+        "poetry.masonry.builders.editable.EditableBuilder",
+        side_effect=Exception("Should not be called"),
+    )
+
+    status_code = install_tester.execute("--no-root --with test,dev")
+    assert status_code == 0
+
+    # Should install main, test, and dev groups
+    installer_groups = set(install_tester.command.installer._groups or [])
+    assert installer_groups == {MAIN_GROUP, "test", "dev"}
+
+
+def test_with_default_group_optionality_and_only_option(
+    install_tester: CommandTester, mocker: MockerFixture
+) -> None:
+    """
+    With default-group-optionality enabled, --only still works as expected.
+    """
+    # Enable the configuration
+    install_tester.command.poetry.config.merge({"default-group-optionality": True})
+
+    mocker.patch.object(install_tester.command.installer, "run", return_value=0)
+    mocker.patch(
+        "poetry.masonry.builders.editable.EditableBuilder",
+        side_effect=Exception("Should not be called"),
+    )
+
+    status_code = install_tester.execute("--no-root --only test")
+    assert status_code == 0
+
+    # Should only install test group
+    installer_groups = set(install_tester.command.installer._groups or [])
+    assert installer_groups == {"test"}
+
+
+def test_config_get_default_group_optionality(config_tester: CommandTester) -> None:
+    """
+    Test getting the default-group-optionality configuration value.
+    """
+    config_tester.execute("default-group-optionality")
+    assert config_tester.status_code == 0
+    assert "false" in config_tester.io.fetch_output().strip().lower()
+
+
+def test_config_set_default_group_optionality(config_tester: CommandTester) -> None:
+    """
+    Test setting the default-group-optionality configuration value.
+    """
+    config_tester.execute("--local default-group-optionality true")
+    assert config_tester.status_code == 0
+
+    config_tester.io.clear_output()
+    config_tester.execute("--local default-group-optionality")
+    assert config_tester.status_code == 0
+    assert "true" in config_tester.io.fetch_output().strip().lower()
+
+
+def test_config_unset_default_group_optionality(config_tester: CommandTester) -> None:
+    """
+    Test unsetting the default-group-optionality configuration value.
+    """
+    config_tester.execute("--local default-group-optionality true")
+    assert config_tester.status_code == 0
+
+    config_tester.execute("--local default-group-optionality --unset")
+    assert config_tester.status_code == 0
+
+    config_tester.io.clear_output()
+    config_tester.execute("default-group-optionality")
+    assert config_tester.status_code == 0
+    # Should revert to default (false)
+    assert "false" in config_tester.io.fetch_output().strip().lower()
+
+
+def test_backward_compatibility(
+    install_tester: CommandTester, mocker: MockerFixture
+) -> None:
+    """
+    Test that existing behavior is maintained when config is not set.
+    """
+    mocker.patch.object(install_tester.command.installer, "run", return_value=0)
+    mocker.patch(
+        "poetry.masonry.builders.editable.EditableBuilder",
+        side_effect=Exception("Should not be called"),
+    )
+
+    # Without setting the config, behavior should be unchanged
+    status_code = install_tester.execute("--no-root")
+    assert status_code == 0
+
+    installer_groups = set(install_tester.command.installer._groups or [])
+    # test and dev should be included by default (not docs since it's optional)
+    assert installer_groups == {MAIN_GROUP, "test", "dev"}