Support volumes at repo creation and duplication (#4035)

* Support volumes at repo creation and duplication

Add `space_volumes` parameter to `create_repo` and `duplicate_repo` in
`HfApi`, and wire it up as `--volume`/`-v` in the CLI `repos create` and
`repos duplicate` commands. Shared volume parsing logic moved from
`jobs.py` to `_cli_utils.py` to avoid duplication.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix tests

* update deprecation warnings

* unrelevant json key

* revert manually added bug

* define a space_args list of tuples

* some parse_volumes optim

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Wauplin

docs/source/en/guides/manage-spaces.md

@@ -201,16 +201,27 @@ Upgraded hardware will be automatically assigned to your Space once it's built.
 
 **6. Mount volumes in your Space**
 
-You can mount Hub resources (models, datasets, or storage buckets) as volumes in your Space's container. This gives your Space direct filesystem access to these resources without having to download them in your code.
+You can mount Hub resources (models, datasets, or storage buckets) as volumes in your Space's container. This gives your Space direct filesystem access to these resources without having to download them in your code. Volumes can be set directly when creating or duplicating a Space:
 
 ```py
 >>> from huggingface_hub import Volume
->>> api.set_space_volumes(
+>>> api.create_repo(
 ...     repo_id=repo_id,
-...     volumes=[
+...     repo_type="space",
+...     space_sdk="gradio",
+...     space_volumes=[
 ...         Volume(type="model", source="username/my-model", mount_path="/models", read_only=True),
-...         Volume(type="dataset", source="username/my-dataset", mount_path="/data", read_only=True),
-...         Volume(type="bucket", source="username/my-bucket", mount_path="/output"),
+...         Volume(type="bucket", source="username/my-bucket", mount_path="/data"),
+...     ],
+... )
+```
+```py
+>>> api.duplicate_repo(
+...     from_id=repo_id,
+...     repo_type="space",
+...     space_volumes=[
+...         Volume(type="model", source="username/my-model", mount_path="/models", read_only=True),
+...         Volume(type="bucket", source="username/my-bucket", mount_path="/data"),
 ...     ],
 ... )
 ```
@@ -223,6 +234,19 @@ You can check which volumes are currently mounted via the Space runtime:
 [Volume(type='model', source='username/my-model', mount_path='/models', read_only=True), ...]
 ```
 
+If you need to update volumes on an existing Space, use [`set_space_volumes`]. Note that this replaces all previously mounted volumes.
+
+```py
+>>> api.set_space_volumes(
+...     repo_id=repo_id,
+...     volumes=[
+...         Volume(type="model", source="username/my-model", mount_path="/models", read_only=True),
+...         Volume(type="dataset", source="username/my-dataset", mount_path="/data", read_only=True),
+...         Volume(type="bucket", source="username/my-bucket", mount_path="/output"),
+...     ],
+... )
+```
+
 To remove all volumes from your Space:
 
 ```py

docs/source/en/package_reference/cli.md

@@ -2934,12 +2934,14 @@ $ hf repos create [OPTIONS] REPO_ID
 * `--secrets-file TEXT`: Read in a file of secret environment variables.
 * `-e, --env TEXT`: Set environment variables. E.g. --env ENV=value
 * `--env-file TEXT`: Read in a file of environment variables.
+* `-v, --volume TEXT`: Mount a volume. Format: hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]. TYPE is one of: models, datasets, spaces, buckets. TYPE defaults to models if omitted. models, datasets and spaces are always mounted read-only. buckets are read+write by default.E.g. -v hf://gpt2:/data or -v hf://datasets/org/ds:/data or -v hf://buckets/org/b:/mnt:ro
 * `--help`: Show this message and exit.
 
 Examples
   $ hf repos create my-model
   $ hf repos create my-dataset --repo-type dataset --private
   $ hf repos create my-space --type space --space-sdk gradio --flavor t4-medium --secrets HF_TOKEN -e THEME=dark --protected
+  $ hf repos create my-space --type space --space-sdk gradio -v hf://gpt2:/models -v hf://buckets/org/b:/data
 
 Learn more
   Use `hf <command> --help` for more information about a command.
@@ -3040,11 +3042,13 @@ $ hf repos duplicate [OPTIONS] FROM_ID [TO_ID]
 * `--secrets-file TEXT`: Read in a file of secret environment variables.
 * `-e, --env TEXT`: Set environment variables. E.g. --env ENV=value
 * `--env-file TEXT`: Read in a file of environment variables.
+* `-v, --volume TEXT`: Mount a volume. Format: hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]. TYPE is one of: models, datasets, spaces, buckets. TYPE defaults to models if omitted. models, datasets and spaces are always mounted read-only. buckets are read+write by default.E.g. -v hf://gpt2:/data or -v hf://datasets/org/ds:/data or -v hf://buckets/org/b:/mnt:ro
 * `--help`: Show this message and exit.
 
 Examples
   $ hf repos duplicate openai/gdpval --type dataset
   $ hf repos duplicate multimodalart/dreambooth-training my-dreambooth --type space --flavor l4x4 --secrets HF_TOKEN --private
+  $ hf repos duplicate org/my-space my-space --type space -v hf://gpt2:/models -v hf://buckets/org/b:/data
 
 Learn more
   Use `hf <command> --help` for more information about a command.

src/huggingface_hub/cli/_cli_utils.py

@@ -31,7 +31,8 @@
 import typer
 from typer.core import TyperCommand, TyperGroup
 
-from huggingface_hub import __version__, constants
+from huggingface_hub import Volume, __version__, constants
+from huggingface_hub.errors import CLIError
 from huggingface_hub.utils import ANSI, get_session, hf_raise_for_status, installation_method, logging, tabulate
 from huggingface_hub.utils._dotenv import load_dotenv
 
@@ -575,6 +576,122 @@ def env_map_to_key_value_list(env_map: dict[str, str | None]) -> list[dict[str,
     return [{"key": k, "value": v or ""} for k, v in env_map.items()]
 
 
+VolumesOpt = Annotated[
+    list[str] | None,
+    typer.Option(
+        "-v",
+        "--volume",
+        help="Mount a volume. Format: hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]. "
+        "TYPE is one of: models, datasets, spaces, buckets. "
+        "TYPE defaults to models if omitted. "
+        "models, datasets and spaces are always mounted read-only. buckets are read+write by default."
+        "E.g. -v hf://gpt2:/data or -v hf://datasets/org/ds:/data or -v hf://buckets/org/b:/mnt:ro",
+    ),
+]
+
+_HF_PREFIX = "hf://"
+_HF_VOLUME_TYPES = {
+    "models": constants.REPO_TYPE_MODEL,
+    "datasets": constants.REPO_TYPE_DATASET,
+    "spaces": constants.REPO_TYPE_SPACE,
+    "buckets": "bucket",
+}
+
+
+def parse_volumes(volumes: list[str] | None) -> "list[Volume] | None":
+    """Parse volume specs from CLI arguments.
+
+    Format: hf://[TYPE/]SOURCE[/PATH]:/MOUNT_PATH[:ro|:rw]
+    Where TYPE is one of: models, datasets, spaces, buckets (defaults to models if omitted).
+    SOURCE is the repo/bucket identifier (e.g. 'username/my-model').
+    PATH is an optional subfolder inside the repo/bucket.
+    MOUNT_PATH starts with '/'.
+    Optional ':ro' or ':rw' suffix for read-only or read-write.
+
+    Examples:
+        hf://gpt2:/data                          (model, implicit type)
+        hf://my-org/my-model:/data                (model, implicit type)
+        hf://models/my-org/my-model:/data         (model, explicit type)
+        hf://datasets/my-org/my-dataset:/data:ro
+        hf://buckets/my-org/my-bucket:/mnt
+        hf://spaces/my-org/my-space:/app
+        hf://datasets/org/ds/train:/data          (with path inside repo)
+        hf://buckets/org/b/sub/dir:/mnt           (with path inside bucket)
+    """
+
+    if not volumes:
+        return None
+
+    result: list[Volume] = []
+    for raw_spec in volumes:
+        # Strip :ro/:rw suffix
+        spec = raw_spec
+        read_only = None
+        if spec.endswith(":ro"):
+            read_only = True
+            spec = spec[:-3]
+        elif spec.endswith(":rw"):
+            read_only = False
+            spec = spec[:-3]
+
+        # Validate hf:// prefix
+        if not spec.startswith(_HF_PREFIX):
+            raise CLIError(
+                f"Invalid volume format: '{raw_spec}'. Source must start with 'hf://'. "
+                f"Expected hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]. E.g. hf://gpt2:/data"
+            )
+        spec = spec[len(_HF_PREFIX) :]
+
+        # Find the mount path: look for :/ pattern
+        colon_slash_idx = spec.find(":/")
+        if colon_slash_idx == -1:
+            raise CLIError(
+                f"Invalid volume format: '{raw_spec}'. Expected hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]. E.g. hf://gpt2:/data"
+            )
+        source_part = spec[:colon_slash_idx]
+        mount_path = spec[colon_slash_idx + 1 :]
+
+        # Parse type from source_part (first segment before /)
+        # Then split remaining into source (namespace/name or name) and optional path.
+        slash_idx = source_part.find("/")
+        if slash_idx == -1:
+            # No slash: bare source like "gpt2" -> model type
+            vol_type_str = constants.REPO_TYPE_MODEL
+            source = source_part
+            path = None
+        else:
+            first_segment = source_part[:slash_idx]
+            if first_segment in _HF_VOLUME_TYPES:
+                vol_type_str = _HF_VOLUME_TYPES[first_segment]
+                remaining = source_part[slash_idx + 1 :]
+            else:
+                # First segment isn't a known type -> model type
+                vol_type_str = constants.REPO_TYPE_MODEL
+                remaining = source_part
+
+            # Split remaining into source (namespace/name) and optional path.
+            # Repo/bucket IDs are "namespace/name" (2 segments) or "name" (1 segment).
+            # Any extra segments are the path inside the repo/bucket.
+            parts = remaining.split("/", 2)
+            if len(parts) >= 3:
+                source = parts[0] + "/" + parts[1]
+                path = parts[2]
+            else:
+                source = remaining
+                path = None
+
+        result.append(
+            Volume(
+                type=vol_type_str,
+                source=source,
+                mount_path=mount_path,
+                read_only=read_only,
+                path=path,
+            )
+        )
+    return result
+
+
 class OutputFormat(str, Enum):
     """Output format for CLI list commands."""
 

src/huggingface_hub/cli/jobs.py

@@ -75,7 +75,7 @@
 
 import typer
 
-from huggingface_hub import SpaceHardware, Volume, constants
+from huggingface_hub import SpaceHardware
 from huggingface_hub.errors import CLIError, HfHubHTTPError
 from huggingface_hub.utils import logging
 from huggingface_hub.utils._cache_manager import _format_size
@@ -88,10 +88,12 @@
     SecretsFileOpt,
     SecretsOpt,
     TokenOpt,
+    VolumesOpt,
     _format_cell,
     api_object_to_dict,
     get_hf_api,
     parse_env_map,
+    parse_volumes,
     print_list_output,
     typer_factory,
 )
@@ -237,18 +239,6 @@ def _parse_namespace_from_job_id(job_id: str, namespace: str | None) -> tuple[st
     ),
 ]
 
-VolumesOpt = Annotated[
-    list[str] | None,
-    typer.Option(
-        "-v",
-        "--volume",
-        help="Mount a volume. Format: hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]. "
-        "TYPE is one of: models, datasets, spaces, buckets. "
-        "TYPE defaults to models if omitted. "
-        "models, datasets and spaces are always mounted read-only. buckets are read+write by default."
-        "E.g. -v hf://gpt2:/data or -v hf://datasets/org/ds:/data or -v hf://buckets/org/b:/mnt:ro",
-    ),
-]
 
 CommandArg = Annotated[
     list[str],
@@ -318,7 +308,7 @@ def jobs_run(
         env=env_map,
         secrets=secrets_map,
         labels=_parse_labels_map(label),
-        volumes=_parse_volumes(volume),
+        volumes=parse_volumes(volume),
         flavor=flavor,
         timeout=timeout,
         namespace=namespace,
@@ -783,7 +773,7 @@ def jobs_uv_run(
         env=env_map,
         secrets=secrets_map,
         labels=_parse_labels_map(label),
-        volumes=_parse_volumes(volume),
+        volumes=parse_volumes(volume),
         flavor=flavor,  # type: ignore[arg-type,misc]
         timeout=timeout,
         namespace=namespace,
@@ -838,7 +828,7 @@ def scheduled_run(
         env=env_map,
         secrets=secrets_map,
         labels=_parse_labels_map(label),
-        volumes=_parse_volumes(volume),
+        volumes=parse_volumes(volume),
         flavor=flavor,
         timeout=timeout,
         namespace=namespace,
@@ -1062,7 +1052,7 @@ def scheduled_uv_run(
         env=env_map,
         secrets=secrets_map,
         labels=_parse_labels_map(label),
-        volumes=_parse_volumes(volume),
+        volumes=parse_volumes(volume),
         flavor=flavor,  # type: ignore[arg-type,misc]
         timeout=timeout,
         namespace=namespace,
@@ -1073,107 +1063,6 @@ def scheduled_uv_run(
 ### UTILS
 
 
-def _parse_volumes(volumes: list[str] | None) -> list[Volume] | None:
-    """Parse volume specs from CLI arguments.
-
-    Format: hf://[TYPE/]SOURCE[/PATH]:/MOUNT_PATH[:ro|:rw]
-    Where TYPE is one of: models, datasets, spaces, buckets (defaults to models if omitted).
-    SOURCE is the repo/bucket identifier (e.g. 'username/my-model').
-    PATH is an optional subfolder inside the repo/bucket.
-    MOUNT_PATH starts with '/'.
-    Optional ':ro' or ':rw' suffix for read-only or read-write.
-
-    Examples:
-        hf://gpt2:/data                          (model, implicit type)
-        hf://my-org/my-model:/data                (model, implicit type)
-        hf://models/my-org/my-model:/data         (model, explicit type)
-        hf://datasets/my-org/my-dataset:/data:ro
-        hf://buckets/my-org/my-bucket:/mnt
-        hf://spaces/my-org/my-space:/app
-        hf://datasets/org/ds/train:/data          (with path inside repo)
-        hf://buckets/org/b/sub/dir:/mnt           (with path inside bucket)
-    """
-    if not volumes:
-        return None
-
-    HF_PREFIX = "hf://"
-    HF_TYPES_MAPPING = {
-        "models": constants.REPO_TYPE_MODEL,
-        "datasets": constants.REPO_TYPE_DATASET,
-        "spaces": constants.REPO_TYPE_SPACE,
-        "buckets": "bucket",
-    }
-
-    result: list[Volume] = []
-    for raw_spec in volumes:
-        # Strip :ro/:rw suffix
-        spec = raw_spec
-        read_only = None
-        if spec.endswith(":ro"):
-            read_only = True
-            spec = spec[:-3]
-        elif spec.endswith(":rw"):
-            read_only = False
-            spec = spec[:-3]
-
-        # Validate hf:// prefix
-        if not spec.startswith(HF_PREFIX):
-            raise CLIError(
-                f"Invalid volume format: '{raw_spec}'. Source must start with 'hf://'. "
-                f"Expected hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]. E.g. hf://gpt2:/data"
-            )
-        spec = spec[len(HF_PREFIX) :]
-
-        # Find the mount path: look for :/ pattern
-        colon_slash_idx = spec.find(":/")
-        if colon_slash_idx == -1:
-            raise CLIError(
-                f"Invalid volume format: '{raw_spec}'. Expected hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]. E.g. hf://gpt2:/data"
-            )
-        source_part = spec[:colon_slash_idx]
-        mount_path = spec[colon_slash_idx + 1 :]
-
-        # Parse type from source_part (first segment before /)
-        # Then split remaining into source (namespace/name or name) and optional path.
-        slash_idx = source_part.find("/")
-        if slash_idx == -1:
-            # No slash: bare source like "gpt2" -> model type
-            vol_type_str = constants.REPO_TYPE_MODEL
-            source = source_part
-            path = None
-        else:
-            first_segment = source_part[:slash_idx]
-            if first_segment in HF_TYPES_MAPPING:
-                vol_type_str = HF_TYPES_MAPPING[first_segment]
-                remaining = source_part[slash_idx + 1 :]
-            else:
-                # First segment isn't a known type -> model type
-                vol_type_str = constants.REPO_TYPE_MODEL
-                remaining = source_part
-
-            # Split remaining into source (namespace/name) and optional path.
-            # Repo/bucket IDs are "namespace/name" (2 segments) or "name" (1 segment).
-            # Any extra segments are the path inside the repo/bucket.
-            parts = remaining.split("/", 2)
-            if len(parts) >= 3:
-                source = parts[0] + "/" + parts[1]
-                path = parts[2]
-            else:
-                source = remaining
-                path = None
-
-        result.append(
-            Volume(
-                type=vol_type_str,
-                source=source,
-                mount_path=mount_path,
-                read_only=read_only,
-                path=path,
-            )
-        )
-    return result
-
-
 def _parse_labels_map(labels: list[str] | None) -> dict[str, str] | None:
     """Parse label key-value pairs from CLI arguments.