Split string values from default_map for multi-value parameters

Fixes #2745

Author: kdeldycke

CHANGES.rst

@@ -40,6 +40,9 @@ Released 2026-04-20
 -   Change :class:`ParameterSource` to an :class:`~enum.IntEnum` and reorder
     its members from most to least explicit, so values can be compared to
     check whether a parameter was explicitly provided. :issue:`2879` :pr:`3248`
+-   Split string values from ``default_map`` for parameters with ``nargs > 1``
+    or :class:`Tuple` type, matching environment variable behavior.
+    :issue:`2745` :pr:`3364`
 
 Version 8.3.2
 -------------

docs/commands.md

@@ -351,6 +351,35 @@ And in action:
     })
 ```
 
+### Multi-value parameters
+
+When a `default_map` value is a string for a parameter with `nargs > 1` or a
+{class}`Tuple` type, the string is split automatically, the same way an
+environment variable would be. By default, values are split on whitespace. See
+[Multiple Options from Environment
+Values](options.md#multiple-options-from-environment-values) for details on
+splitting behavior.
+
+```python
+default_map = {
+    "draw": {
+        "point": "3 4",  # split into ("3", "4") for nargs=2
+        "color": "red",  # passed as-is for nargs=1
+    }
+}
+```
+
+You can also pass an already-structured tuple or list, which will be used as-is
+without splitting:
+
+```python
+default_map = {
+    "draw": {
+        "point": (3, 4),  # used directly
+    }
+}
+```
+
 ## Context Defaults
 
 ```{versionadded} 2.0

src/click/core.py

@@ -2356,6 +2356,11 @@ def consume_value(
                 value = default_map_value
                 source = ParameterSource.DEFAULT_MAP
 
+                # A string from default_map must be split for multi-value
+                # parameters, matching value_from_envvar behavior.
+                if isinstance(value, str) and self.nargs != 1:
+                    value = self.type.split_envvar_value(value)
+
         if value is UNSET:
             default_value = self.get_default(ctx)
             if default_value is not UNSET:

tests/test_defaults.py

@@ -357,6 +357,43 @@ def cli(value):
     assert result.output == repr(expected)
 
 
+@pytest.mark.parametrize(
+    ("default_map", "option_kwargs", "cli_args", "expected"),
+    [
+        # String is split for nargs=2 option.
+        ({"point": "3 4"}, {"nargs": 2, "type": int}, [], (3, 4)),
+        # String is split for explicit Tuple type.
+        ({"point": "hello world"}, {"type": (str, str)}, [], ("hello", "world")),
+        # Already-structured tuple passes through unchanged.
+        ({"point": ("a", "b")}, {"nargs": 2}, [], ("a", "b")),
+        # Already-structured list passes through unchanged.
+        ({"point": [5, 6]}, {"nargs": 2, "type": int}, [], (5, 6)),
+        # CLI args override default_map for nargs > 1.
+        (
+            {"point": "3 4"},
+            {"nargs": 2, "type": int},
+            ["--point", "10", "20"],
+            (10, 20),
+        ),
+    ],
+)
+def test_default_map_nargs(runner, default_map, option_kwargs, cli_args, expected):
+    """A string in ``default_map`` for an option with ``nargs > 1`` should be
+    split the same way an environment variable string is split.
+
+    Regression test for https://github.com/pallets/click/issues/2745.
+    """
+
+    @click.command()
+    @click.option("--point", **option_kwargs)
+    def cli(point):
+        click.echo(repr(point))
+
+    result = runner.invoke(cli, cli_args, default_map=default_map)
+    assert result.exit_code == 0
+    assert result.output.strip() == repr(expected)
+
+
 def test_unset_in_default_map(runner):
     """An ``UNSET`` value in ``default_map`` should be treated as if
     the key is absent, and so fallback to the parameter's own default.