feat(jobs): add volume mounting support for buckets and repos (#3936)

* feat(jobs): add volume mounting support for buckets and repos

Add `volumes` parameter to `run_job`, `create_scheduled_job`,
`run_uv_job`, and `create_scheduled_uv_job` to mount HuggingFace
Buckets and Repos (models, datasets, spaces) as volumes in job
containers.

- Add `JobVolume` dataclass and `JobVolumeType` enum
- Add `volumes` field to `JobInfo` and `JobSpec` responses
- Add `-v/--volume` CLI option with Docker-like syntax
  (e.g. `-v models/gpt2:/data` or `-v buckets/org/bucket:/mnt:ro`)
- Serialize volumes to camelCase for the Hub API

* style: fix ruff formatting

* docs: regenerate CLI reference for volume option

* feat: default volume type to model, remove plural aliases

* refactor: replace _VOLUME_TYPE_ALIASES dict with _VOLUME_TYPES set

* test: add tests for JobVolume, _parse_volumes, and volume serialization

* refactor: improve code quality per review

- Remove dead isinstance check in _create_job_spec serialization
- Add volumes field to JobInfo docstring
- Preserve original input in _parse_volumes error messages
- Restructure tests: parametrize, merge into existing classes, top-level imports

* docs

* Apply suggestions from code review

Co-authored-by: Daniel van Strien <davanstrien@users.noreply.github.com>

* Rename JobVolume to Volume + remove JobVolumeType enum

* fix

* better test

* check tests

* updated parsing logic

* useless line

* Update docs/source/en/guides/jobs.md

Co-authored-by: célina <hanouticelina@gmail.com>

* Update src/huggingface_hub/cli/jobs.py

Co-authored-by: célina <hanouticelina@gmail.com>

* no more misleading REPO_TYPE_BUCKET

* Update docs/source/en/guides/cli.md

Co-authored-by: célina <hanouticelina@gmail.com>

* Update docs/source/en/guides/cli.md

Co-authored-by: célina <hanouticelina@gmail.com>

* added examples

---------

Co-authored-by: Quentin Lhoest <lhoest.q@gmail.com>
Co-authored-by: Quentin Lhoest <42851186+lhoestq@users.noreply.github.com>
Co-authored-by: Daniel van Strien <davanstrien@users.noreply.github.com>
Co-authored-by: Lucain Pouget <lucainp@gmail.com>
Co-authored-by: Lucain <lucain@huggingface.co>
Co-authored-by: célina <hanouticelina@gmail.com>

Author: 5 people

docs/source/en/guides/cli.md

@@ -1571,6 +1571,37 @@ Available `--flavor` options:
 
 (updated in 07/2025 from Hugging Face [suggested_hardware docs](https://huggingface.co/docs/hub/en/spaces-config-reference))
 
+## Volumes
+
+Mount a volume on the Job's disk using `-v` or `--volume`.
+
+You can mount any Hugging Face Repository (model/dataset/space) or [Storage Bucket](/docs/hub/storage-buckets) using the `hf://` URL scheme. For example:
+
+* mount a model repository: `-v hf://openai/gpt-oss-120b:/model`
+* mount a model repository (explicit type): `-v hf://models/openai/gpt-oss-120b:/model`
+* mount a dataset repository: `-v hf://datasets/HuggingFaceFW/fineweb:/data`
+* mount a storage bucket: `-v hf://buckets/username/my-bucket:/mnt`
+* mount a space: `-v hf://spaces/username/my-space:/app`
+* mount a subfolder inside a repo: `-v hf://datasets/org/ds/train:/data`
+
+Then you can use the mounted volume as a local directory:
+
+```bash
+# Docker Job with a mounted volume as input
+>>> hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/dataset \
+...     duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"
+
+# UV Job with a mounted volume to save checkpoints when training a model
+>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
+...     sft.py --output-dir /training-outputs/training-v3-final ...
+```
+
+Models, datasets and spaces are always mounted read-only. Storage buckets are read+write by default — this is especially useful for data that changes frequently, as files can be overwritten or deleted in place.
+
+Use `:ro` to enable read-only:
+
+* mount a storage bucket in read-only: `-v hf://buckets/username/my-bucket:/mnt:ro`
+
 ### Labels
 
 Add labels to a Job using `-l` or `--label`. Labels are a key=value pairs that applies metadata to a Job. To label a Job with two labels, repeat the label flag (`-l` or `--label`):

docs/source/en/guides/jobs.md

@@ -216,6 +216,42 @@ Available `flavor` options:
 
 That's it! You're now running code on Hugging Face's infrastructure.
 
+## Mount a volume
+
+Mount a volume on the Jobs's disk using a list of [`Volume`].
+
+You can mount any Hugging Face Repository (model/dataset/space) or [Storage Bucket](/docs/hub/storage-buckets). For example:
+
+* mount a model repository: `Volume(type="model", source="openai/gpt-oss-120b", mount_path="/model")`
+* mount a dataset repository: `Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")`
+* mount a storage bucket: `Volume(type="bucket", source="username/my-bucket", mount_path="/mnt")`
+
+Then you can use the mounted volume as a local directory:
+
+```python
+>>> from huggingface_hub import run_job, Volume
+>>> job = run_job(
+...     image="duckdb/duckdb",
+...     command=["duckdb", "-c", "SELECT * FROM '/data/**/*.parquet' LIMIT 5"],
+...     volumes=[Volume(type="dataset", source="HuggingFaceFW/fineweb", mount_path="/data")],
+... )
+```
+
+You can also write to a mounted bucket, for example, to save checkpoints when training a model:
+
+```python
+>>> from huggingface_hub import run_uv_job, Volume
+>>> script = "my_sft.py"
+>>> script_args = ["--output_dir", "/training-outputs/training-v3-final", ...]
+>>> checkpoints_bucket = Volume(type="bucket", source="username/my-bucket", mount_path="/training-outputs")
+>>> run_uv_job(script, script_args=script_args, volumes=[checkpoints_bucket])
+```
+
+By default, mounted storage buckets have read+write abilities.
+This is especially useful for storage buckets, which provide fast, mutable storage for data that changes frequently — files can be overwritten or deleted in place.
+
+Use `read_only=True` to enable read-only: `Volume(type="bucket", read_only=True, ...)`.
+
 ## Configure Job Timeout
 
 Jobs have a default timeout (30 minutes), after which they will automatically stop. This is important to know when running long-running tasks like model training.

docs/source/en/package_reference/cli.md

@@ -2157,6 +2157,7 @@ $ hf jobs run [OPTIONS] IMAGE COMMAND...
 * `-e, --env TEXT`: Set environment variables. E.g. --env ENV=value
 * `-s, --secrets TEXT`: Set secret environment variables. E.g. --secrets SECRET=value or `--secrets HF_TOKEN` to pass your Hugging Face token.
 * `-l, --label TEXT`: Set labels. E.g. --label KEY=VALUE or --label LABEL
+* `-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
 * `--env-file TEXT`: Read in a file of environment variables.
 * `--secrets-file TEXT`: Read in a file of secret environment variables.
 * `--flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|sprx8|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|inf2x6]`: Flavor for the hardware, as in HF Spaces. Run 'hf jobs hardware' to list available flavors. Defaults to `cpu-basic`.
@@ -2170,6 +2171,7 @@ Examples
   $ hf jobs run python:3.12 python -c 'print("Hello!")'
   $ hf jobs run -e FOO=foo python:3.12 python script.py
   $ hf jobs run --secrets HF_TOKEN python:3.12 python script.py
+  $ hf jobs run -v hf://gpt2:/data -v hf://buckets/org/b:/mnt python:3.12 python script.py
 
 Learn more
   Use `hf <command> --help` for more information about a command.
@@ -2335,6 +2337,7 @@ $ hf jobs scheduled run [OPTIONS] SCHEDULE IMAGE COMMAND...
 * `-e, --env TEXT`: Set environment variables. E.g. --env ENV=value
 * `-s, --secrets TEXT`: Set secret environment variables. E.g. --secrets SECRET=value or `--secrets HF_TOKEN` to pass your Hugging Face token.
 * `-l, --label TEXT`: Set labels. E.g. --label KEY=VALUE or --label LABEL
+* `-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
 * `--env-file TEXT`: Read in a file of environment variables.
 * `--secrets-file TEXT`: Read in a file of secret environment variables.
 * `--flavor [cpu-basic|cpu-upgrade|cpu-performance|cpu-xl|sprx8|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|a100x4|a100x8|h200|h200x2|h200x4|h200x8|inf2x6]`: Flavor for the hardware, as in HF Spaces. Run 'hf jobs hardware' to list available flavors. Defaults to `cpu-basic`.
@@ -2422,6 +2425,7 @@ $ hf jobs scheduled uv run [OPTIONS] SCHEDULE SCRIPT [SCRIPT_ARGS]...
 * `-e, --env TEXT`: Set environment variables. E.g. --env ENV=value
 * `-s, --secrets TEXT`: Set secret environment variables. E.g. --secrets SECRET=value or `--secrets HF_TOKEN` to pass your Hugging Face token.
 * `-l, --label TEXT`: Set labels. E.g. --label KEY=VALUE or --label LABEL
+* `-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
 * `--env-file TEXT`: Read in a file of environment variables.
 * `--secrets-file TEXT`: Read in a file of secret environment variables.
 * `--timeout TEXT`: Max duration: int/float with s (seconds, default), m (minutes), h (hours) or d (days).
@@ -2508,6 +2512,7 @@ $ hf jobs uv run [OPTIONS] SCRIPT [SCRIPT_ARGS]...
 * `-e, --env TEXT`: Set environment variables. E.g. --env ENV=value
 * `-s, --secrets TEXT`: Set secret environment variables. E.g. --secrets SECRET=value or `--secrets HF_TOKEN` to pass your Hugging Face token.
 * `-l, --label TEXT`: Set labels. E.g. --label KEY=VALUE or --label LABEL
+* `-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
 * `--env-file TEXT`: Read in a file of environment variables.
 * `--secrets-file TEXT`: Read in a file of secret environment variables.
 * `--timeout TEXT`: Max duration: int/float with s (seconds, default), m (minutes), h (hours) or d (days).
@@ -2522,6 +2527,7 @@ Examples
   $ hf jobs uv run my_script.py
   $ hf jobs uv run ml_training.py --flavor a10g-small
   $ hf jobs uv run --with transformers train.py
+  $ hf jobs uv run -v hf://gpt2:/data -v hf://buckets/org/b:/mnt script.py
 
 Learn more
   Use `hf <command> --help` for more information about a command.

docs/source/en/package_reference/jobs.md

@@ -32,3 +32,7 @@ Check the [`HfApi`] documentation page for the reference of methods to manage yo
 ### JobStatus
 
 [[autodoc]] JobStatus
+
+### Volume
+
+[[autodoc]] Volume

src/huggingface_hub/__init__.py

@@ -83,6 +83,7 @@
         "JobOwner",
         "JobStage",
         "JobStatus",
+        "Volume",
     ],
     "_login": [
         "auth_list",
@@ -858,6 +859,7 @@
     "VisualQuestionAnsweringInputData",
     "VisualQuestionAnsweringOutputElement",
     "VisualQuestionAnsweringParameters",
+    "Volume",
     "WebhookInfo",
     "WebhookPayload",
     "WebhookPayloadComment",
@@ -1205,6 +1207,7 @@ def __dir__():
         JobOwner,  # noqa: F401
         JobStage,  # noqa: F401
         JobStatus,  # noqa: F401
+        Volume,  # noqa: F401
     )
     from ._login import (
         auth_list,  # noqa: F401

src/huggingface_hub/_jobs_api.py

@@ -15,13 +15,51 @@
 from dataclasses import dataclass
 from datetime import datetime
 from enum import Enum
-from typing import Any, Optional, Union
+from typing import Any, Literal, Optional, Union
 
 from huggingface_hub import constants
 from huggingface_hub._space_api import SpaceHardware
 from huggingface_hub.utils._datetime import parse_datetime
 
 
+@dataclass
+class Volume:
+    """
+    Describes a volume to mount in a Job container.
+
+    Args:
+        type (`str`):
+            Type of volume: `"bucket"`, `"model"`, `"dataset"`, or `"space"`.
+        source (`str`):
+            Source identifier, e.g. `"username/my-bucket"` or `"username/my-model"`.
+        mount_path (`str`):
+            Mount path inside the container, e.g. `"/data"`. Must start with `/`.
+        revision (`str` or `None`):
+            Git revision (only for repos, defaults to `"main"`).
+        read_only (`bool` or `None`):
+            Read-only mount. Forced `True` for repos, defaults to `False` for buckets.
+        path (`str` or `None`):
+            Subfolder prefix inside the bucket/repo to mount, e.g. `"path/to/dir"`.
+    """
+
+    type: Literal["bucket", "model", "dataset", "space"]
+    source: str
+    mount_path: str
+    revision: Optional[str] = None
+    read_only: Optional[bool] = None
+    path: Optional[str] = None
+
+    def __init__(self, **kwargs) -> None:
+        self.type = kwargs.get("type", "model")
+        self.source = kwargs["source"]
+        mount_path = kwargs.get("mountPath")
+        self.mount_path = mount_path if mount_path is not None else kwargs["mount_path"]
+        self.revision = kwargs.get("revision")
+        read_only = kwargs.get("readOnly")
+        self.read_only = read_only if read_only is not None else kwargs.get("read_only")
+        self.path = kwargs.get("path")
+
+
 class JobStage(str, Enum):
     """
     Enumeration of possible stage of a Job on the Hub.
@@ -84,6 +122,8 @@ class JobInfo:
             E.g. `"cpu-basic"`.
         labels (`dict[str, str]` or `None`):
             Labels to attach to the job (key-value pairs).
+        volumes (`list[Volume]` or `None`):
+            Volumes mounted in the job container (buckets, models, datasets, spaces).
         status: (`JobStatus` or `None`):
             Status of the Job, e.g. `JobStatus(stage="RUNNING", message=None)`
             See [`JobStage`] for possible stage values.
@@ -119,6 +159,7 @@ class JobInfo:
     secrets: Optional[dict[str, Any]]
     flavor: Optional[SpaceHardware]
     labels: Optional[dict[str, str]]
+    volumes: Optional[list[Volume]]
     status: JobStatus
     owner: JobOwner
 
@@ -140,6 +181,8 @@ def __init__(self, **kwargs) -> None:
         self.secrets = kwargs.get("secrets")
         self.flavor = kwargs.get("flavor")
         self.labels = kwargs.get("labels")
+        volumes = kwargs.get("volumes")
+        self.volumes = [Volume(**v) for v in volumes] if volumes else None
         status = kwargs.get("status", {})
         self.status = JobStatus(stage=status["stage"], message=status.get("message"))
 
@@ -161,6 +204,7 @@ class JobSpec:
     tags: Optional[list[str]]
     arch: Optional[str]
     labels: Optional[dict[str, str]]
+    volumes: Optional[list[Volume]]
 
     def __init__(self, **kwargs) -> None:
         self.docker_image = kwargs.get("dockerImage") or kwargs.get("docker_image")
@@ -174,6 +218,8 @@ def __init__(self, **kwargs) -> None:
         self.tags = kwargs.get("tags")
         self.arch = kwargs.get("arch")
         self.labels = kwargs.get("labels")
+        volumes = kwargs.get("volumes")
+        self.volumes = [Volume(**v) for v in volumes] if volumes else None
 
 
 @dataclass
@@ -363,6 +409,7 @@ def _create_job_spec(
     flavor: Optional[SpaceHardware],
     timeout: Optional[Union[int, float, str]],
     labels: Optional[dict[str, str]] = None,
+    volumes: Optional[list[Volume]] = None,
 ) -> dict[str, Any]:
     # prepare job spec to send to HF Jobs API
     job_spec: dict[str, Any] = {
@@ -384,6 +431,19 @@ def _create_job_spec(
     # labels are optional
     if labels:
         job_spec["labels"] = labels
+    # volumes are optional
+    if volumes:
+        job_spec["volumes"] = [
+            {
+                "type": vol.type,
+                "source": vol.source,
+                "mountPath": vol.mount_path,
+                **({"revision": vol.revision} if vol.revision is not None else {}),
+                **({"readOnly": vol.read_only} if vol.read_only is not None else {}),
+                **({"path": vol.path} if vol.path is not None else {}),
+            }
+            for vol in volumes
+        ]
     # input is either from docker hub or from HF spaces
     for prefix in (
         "https://huggingface.co/spaces/",