From 8efc0a954dfd20cd8f4fd7987f1e51531f313dae Mon Sep 17 00:00:00 2001 From: Assaf Vayner Date: Mon, 21 Sep 2026 03:53:56 -0700 Subject: [PATCH 01/14] [HfFileSystem] Make lpath optional in get_file (fsspec>=2026.9.0) (#4951) * [HfFileSystem] Make `lpath` optional in `get_file` (fsspec>=2026.9.0) fsspec 2026.9.0 made `lpath` optional in `AbstractFileSystem.get_file` (it can be omitted when `outfile` is provided). Our override kept it required, which the latest `ty` flags as an invalid method override and fails CI. Make `lpath=None` in the signature and raise a clear ValueError if neither `lpath` nor `outfile` is provided. No behavior change otherwise. * fix get_file branching to match fsspec --------- Co-authored-by: Celina Hanouti --- src/huggingface_hub/hf_file_system.py | 33 +++++++++++++-------------- tests/test_hf_file_system.py | 17 ++++++++++++++ 2 files changed, 33 insertions(+), 17 deletions(-) diff --git a/src/huggingface_hub/hf_file_system.py b/src/huggingface_hub/hf_file_system.py index 46c8ded81ac..18121141f5e 100644 --- a/src/huggingface_hub/hf_file_system.py +++ b/src/huggingface_hub/hf_file_system.py @@ -8,7 +8,7 @@ from dataclasses import dataclass, field from datetime import datetime from itertools import chain -from pathlib import Path, PurePosixPath +from pathlib import PurePosixPath from typing import Any, NoReturn, Union from urllib.parse import quote, unquote @@ -1077,7 +1077,7 @@ def url(self, path: str) -> str: url = url.replace("/resolve/", "/tree/", 1) return url - def get_file(self, rpath, lpath, callback=_DEFAULT_CALLBACK, outfile=None, **kwargs) -> None: + def get_file(self, rpath, lpath=None, callback=_DEFAULT_CALLBACK, outfile=None, **kwargs) -> None: """ Copy single remote file to local. @@ -1087,8 +1087,8 @@ def get_file(self, rpath, lpath, callback=_DEFAULT_CALLBACK, outfile=None, **kwa Args: rpath (`str`): Remote path to download from. - lpath (`str`): - Local path to download to. + lpath (`str`, *optional*): + Local path to download to. Can be omitted if `outfile` is provided. callback (`Callback`, *optional*): Optional callback to track download progress. Defaults to no callback. outfile (`IO`, *optional*): @@ -1106,21 +1106,20 @@ def get_file(self, rpath, lpath, callback=_DEFAULT_CALLBACK, outfile=None, **kwa # and let's not handle custom kwargs return super().get_file(rpath, lpath, callback=callback, outfile=outfile, **kwargs) - # Taken from https://github.com/fsspec/filesystem_spec/blob/47b445ae4c284a82dd15e0287b1ffc410e8fc470/fsspec/spec.py#L883 - if isfilelike(lpath): - outfile = lpath - elif self.isdir(rpath): - os.makedirs(lpath, exist_ok=True) - return None - - if isinstance(lpath, (str, Path)): # otherwise, let's assume it's a file-like object - os.makedirs(os.path.dirname(lpath), exist_ok=True) - - # Open file if not already open + # Adapted from https://github.com/fsspec/filesystem_spec/blob/0f76baaae4a227b085b18e8469e6cc1792a95ade/fsspec/spec.py#L975 close_file = False if outfile is None: - outfile = open(lpath, "wb") - close_file = True + if lpath is None: + raise ValueError("Either `lpath` or `outfile` must be provided.") + if isfilelike(lpath): + outfile = lpath + elif self.isdir(rpath): + os.makedirs(lpath, exist_ok=True) + return None + else: + os.makedirs(os.path.dirname(lpath), exist_ok=True) + outfile = open(lpath, "wb") + close_file = True initial_pos = outfile.tell() # Custom implementation of `get_file` to use `http_get`. diff --git a/tests/test_hf_file_system.py b/tests/test_hf_file_system.py index 3b91dff48d8..55940e56ef8 100644 --- a/tests/test_hf_file_system.py +++ b/tests/test_hf_file_system.py @@ -335,6 +335,23 @@ def test_get_file_with_temporary_file(self): temp_file.seek(0) assert temp_file.read() == b"dummy text data" + def test_get_file_without_lpath(self): + with tempfile.TemporaryFile() as temp_file: + self.hffs.get_file(self.text_file, outfile=temp_file) + temp_file.seek(0) + assert temp_file.read() == b"dummy text data" + + def test_get_file_outfile_takes_precedence_over_filelike_lpath(self): + with tempfile.TemporaryFile() as lpath, tempfile.TemporaryFile() as outfile: + self.hffs.get_file(self.text_file, lpath, outfile=outfile) + outfile.seek(0) + assert outfile.read() == b"dummy text data" + assert lpath.tell() == 0 + + def test_get_file_without_lpath_and_outfile_raises(self): + with pytest.raises(ValueError, match="Either `lpath` or `outfile` must be provided"): + self.hffs.get_file(self.text_file) + def test_get_file_with_temporary_folder(self): # Test passing a file path works with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as temp_dir: From 4c80e7ee7617b149719bc2d883451c0489f3531a Mon Sep 17 00:00:00 2001 From: Sreekant Baheti <60787859+Sreekant13@users.noreply.github.com> Date: Mon, 21 Sep 2026 06:53:54 -0700 Subject: [PATCH 02/14] Fix `format_timesince` showing "60 seconds ago" / "60 minutes ago" / "24 hours ago" instead of rolling over (#4943) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Roll `format_timesince` over to the next unit at the boundary `format_timesince` showed "60 seconds ago", "60 minutes ago" and "24 hours ago" at the exact unit boundaries instead of rolling over to the next unit, because the per-unit max values were 60/60/24 rather than 59/59/23. Days (6 -> 1 week) and months (11 -> 1 year) already rolled correctly; this brings seconds, minutes and hours in line. Adds the boundary cases to the test. * Update src/huggingface_hub/utils/_parsing.py --------- Co-authored-by: célina --- src/huggingface_hub/utils/_parsing.py | 8 ++++---- tests/test_utils_parsing.py | 8 ++++++++ 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/src/huggingface_hub/utils/_parsing.py b/src/huggingface_hub/utils/_parsing.py index eeddee70f64..d890f75161c 100644 --- a/src/huggingface_hub/utils/_parsing.py +++ b/src/huggingface_hub/utils/_parsing.py @@ -97,10 +97,10 @@ def format_timesince(ts: float) -> str: Vaguely inspired by Django's `timesince` formatter. """ _TIMESINCE_CHUNKS = ( - # Label, divider, max value - ("second", 1, 60), - ("minute", 60, 60), - ("hour", 60 * 60, 24), + # Label, divider, max value shown before rolling over to the next unit (e.g. 59 -> "1 minute ago" at 60s) + ("second", 1, 59), + ("minute", 60, 59), + ("hour", 60 * 60, 23), ("day", 60 * 60 * 24, 6), ("week", 60 * 60 * 24 * 7, 6), ("month", 60 * 60 * 24 * 30, 11), diff --git a/tests/test_utils_parsing.py b/tests/test_utils_parsing.py index d39a1cfb95e..28b128ec65f 100644 --- a/tests/test_utils_parsing.py +++ b/tests/test_utils_parsing.py @@ -86,6 +86,14 @@ def test_parse_duration_invalid(value): (1000, "17 minutes ago"), (4000, "1 hour ago"), (8000, "2 hours ago"), + # Unit boundaries must roll over to the next unit, not show e.g. + # "60 seconds ago" / "60 minutes ago" / "24 hours ago". + (59, "59 seconds ago"), + (60, "1 minute ago"), + (59 * 60, "59 minutes ago"), + (60 * 60, "1 hour ago"), + (23 * 60 * 60, "23 hours ago"), + (24 * 60 * 60, "1 day ago"), ], ) def test_format_timesince(value, expected): From 55668e24370903ce802da067030cb5a2cb5afa08 Mon Sep 17 00:00:00 2001 From: DltsumCtnori Date: Mon, 21 Sep 2026 22:18:19 +0800 Subject: [PATCH 03/14] Fix Windows conftest erroring test subsets on lazy-loaded file_download submodule (#4945) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Fix Windows conftest failing on lazy-loaded `file_download` submodule The `disable_symlinks_on_windows_ci` autouse fixture (active on Windows via `DISABLE_SYMLINKS_IN_WINDOWS_TESTS=1` in pyproject.toml) accesses `huggingface_hub.file_download` as a monkeypatch target. Since the package loads submodules lazily, this attribute only exists if something else already imported the submodule. Running a test subset that doesn't (e.g. `pytest tests/test_utils_headers.py`) errors every test at setup with `AttributeError: No huggingface_hub attribute file_download`. Use the string-target form of `monkeypatch.setattr`, which imports the submodule itself. Co-Authored-By: Claude Code * Update tests/conftest.py --------- Co-authored-by: dltsum Co-authored-by: Claude Code Co-authored-by: célina --- tests/conftest.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tests/conftest.py b/tests/conftest.py index ea02123495e..800a440a136 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -101,8 +101,7 @@ def __getitem__(self, __key: str) -> bool: if os.name == "nt" and os.environ.get("DISABLE_SYMLINKS_IN_WINDOWS_TESTS"): monkeypatch.setattr( - huggingface_hub.file_download, - "_are_symlinks_supported_in_dir", + "huggingface_hub.file_download._are_symlinks_supported_in_dir", FakeSymlinkDict(), ) From 7ce68b9bd8326b781b507de66d93e1dd3657af47 Mon Sep 17 00:00:00 2001 From: Daniel van Strien Date: Mon, 21 Sep 2026 16:09:35 +0100 Subject: [PATCH 04/14] [Webhooks] Allow `bucket` as a watched item type (#4958) The Hub accepts buckets as watched items, but `hf webhooks create --watch bucket:...` fails client-side because the CLI derives its valid types from `WebhookWatchedItem.type`, which lacked "bucket". Claude-Session: https://claude.ai/code/session_015YLK3QPDdiiZGuDxoFrEag Co-authored-by: Claude Opus 5 (1M context) --- docs/source/en/guides/cli.md | 2 +- src/huggingface_hub/hf_api.py | 11 ++++++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/source/en/guides/cli.md b/docs/source/en/guides/cli.md index abcaed3c3f7..088808090e8 100644 --- a/docs/source/en/guides/cli.md +++ b/docs/source/en/guides/cli.md @@ -2408,7 +2408,7 @@ Or create a webhook that triggers a Job instead: >>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-c ``` -The `--watch` option uses the format `type:name` where type is one of `model`, `dataset`, `space`, `org`, or `user`. It can be repeated to watch multiple items. Use `--domain` to filter events to `repo` or `discussions`, and `--secret` to set a signing secret. +The `--watch` option uses the format `type:name` where type is one of `model`, `dataset`, `space`, `bucket`, `org`, or `user`. It can be repeated to watch multiple items. Use `--domain` to filter events to `repo` or `discussions`, and `--secret` to set a signing secret. ### Update a webhook diff --git a/src/huggingface_hub/hf_api.py b/src/huggingface_hub/hf_api.py index b23596c1dc6..86cedbafdd8 100644 --- a/src/huggingface_hub/hf_api.py +++ b/src/huggingface_hub/hf_api.py @@ -595,13 +595,14 @@ class WebhookWatchedItem: """Data structure containing information about the items watched by a webhook. Attributes: - type (`Literal["dataset", "model", "org", "space", "user"]`): - Type of the item to be watched. Can be one of `["dataset", "model", "org", "space", "user"]`. + type (`Literal["bucket", "dataset", "model", "org", "space", "user"]`): + Type of the item to be watched. Can be one of `["bucket", "dataset", "model", "org", "space", "user"]`. name (`str`): - Name of the item to be watched. Can be the username, organization name, model name, dataset name or space name. + Name of the item to be watched. Can be the username, organization name, model name, dataset name, space name + or bucket name. """ - type: Literal["dataset", "model", "org", "space", "user"] + type: Literal["bucket", "dataset", "model", "org", "space", "user"] name: str @@ -11263,7 +11264,7 @@ def create_webhook( ID of the source Job to trigger with the webhook payload in the environment variable WEBHOOK_PAYLOAD. Additional environment variables are available for convenience: WEBHOOK_REPO_ID, WEBHOOK_REPO_TYPE and WEBHOOK_SECRET. watched (`list[WebhookWatchedItem]`): - List of [`WebhookWatchedItem`] to be watched by the webhook. It can be users, orgs, models, datasets or spaces. + List of [`WebhookWatchedItem`] to be watched by the webhook. It can be users, orgs, models, datasets, spaces or buckets. Watched items can also be provided as plain dictionaries. domains (`list[Literal["repo", "discussion"]]`, optional): List of domains to watch. It can be "repo", "discussion" or both. From 7025391af643a9ea220f0ba2c4570250af2c1a3e Mon Sep 17 00:00:00 2001 From: Kayvan Zahiri <123409429+Kayvan-Zahiri@users.noreply.github.com> Date: Tue, 22 Sep 2026 03:42:24 -0700 Subject: [PATCH 05/14] [MCP] Follow nextCursor when listing tools in MCPClient (#4960) * [MCP] Follow nextCursor when listing tools in MCPClient add_mcp_server called list_tools() once, so tools past a server's first tools/list page were never registered, and allowed_tools could filter down to nothing. Page through with the cursor until nextCursor is empty. * [MCP] Keep the first list_tools() call cursor-free and require mcp>=1.9.4 mcp 1.8.x's list_tools() takes no cursor at all, and before 1.9.4 the cursor is sent outside params, so a paginating server returns page one forever. Call list_tools() plainly first so non-paginated servers behave as before, and raise the extra's floor to the first release that paginates correctly. --- setup.py | 2 +- src/huggingface_hub/inference/_mcp/mcp_client.py | 14 +++++++++----- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/setup.py b/setup.py index eecbb10c026..4715d73580d 100644 --- a/setup.py +++ b/setup.py @@ -48,7 +48,7 @@ def get_version() -> str: extras["hf_xet"] = [HF_XET_VERSION] -extras["mcp"] = ["mcp>=1.8.0, <2.0.0"] +extras["mcp"] = ["mcp>=1.9.4, <2.0.0"] # list_tools(cursor=...) only paginates correctly from 1.9.4 extras["testing"] = ( extras["oauth"] diff --git a/src/huggingface_hub/inference/_mcp/mcp_client.py b/src/huggingface_hub/inference/_mcp/mcp_client.py index 7331d13fa61..00c0b572fd9 100644 --- a/src/huggingface_hub/inference/_mcp/mcp_client.py +++ b/src/huggingface_hub/inference/_mcp/mcp_client.py @@ -210,17 +210,21 @@ async def add_mcp_server(self, type: ServerType, **params: Any): logger.debug("Initializing session...") await session.initialize() - # List available tools + # List available tools, following `nextCursor` since servers may paginate tools/list response = await session.list_tools() - logger.debug("Connected to server with tools:", [tool.name for tool in response.tools]) + tools: list[mcp_types.Tool] = list(response.tools) + while response.nextCursor: + response = await session.list_tools(cursor=response.nextCursor) + tools.extend(response.tools) + logger.debug("Connected to server with tools:", [tool.name for tool in tools]) # Filter tools based on allowed_tools configuration - filtered_tools = response.tools + filtered_tools = tools if allowed_tools is not None: - filtered_tools = [tool for tool in response.tools if tool.name in allowed_tools] + filtered_tools = [tool for tool in tools if tool.name in allowed_tools] logger.debug( - f"Tool filtering applied. Using {len(filtered_tools)} of {len(response.tools)} available tools: {[tool.name for tool in filtered_tools]}" + f"Tool filtering applied. Using {len(filtered_tools)} of {len(tools)} available tools: {[tool.name for tool in filtered_tools]}" ) for tool in filtered_tools: From 80aef09476214832266f0b5fea7c09c7ae31d1aa Mon Sep 17 00:00:00 2001 From: Sharvil Saxena <97365286+sharziki@users.noreply.github.com> Date: Tue, 22 Sep 2026 06:42:34 -0400 Subject: [PATCH 06/14] Align the `hf` package's python_requires with huggingface_hub (#4959) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * [CLI] Align the `hf` package's python_requires with huggingface_hub `huggingface_hub` moved to `python_requires=">=3.10.0"` in #4856, but `utils/hf/setup.py` was left at `">=3.9.0"`. The `hf` package is only a console script that imports `huggingface_hub` and pins `huggingface_hub=={version}`, so the published metadata now contradicts itself: PyPI shows `hf` 1.32.0 as `Requires-Python: >=3.9.0` while the `huggingface_hub==1.32.0` it depends on is `>=3.10.0`. On Python 3.9 that resolves two ways, both wrong: $ pip install hf Successfully installed hf-1.8.0 huggingface_hub-1.8.0 # silently 24 versions stale $ pip install hf==1.32.0 ERROR: Could not find a version that satisfies the requirement huggingface_hub==1.32.0 (from hf) ERROR: No matching distribution found for huggingface_hub==1.32.0 The first is the damaging one: `uvx hf`, the usage the README documents, reports version 1.8.0 on a 3.9 interpreter with no error and no warning, so a user can be years out of date without any signal. Set `python_requires` to match the root setup.py and add a test asserting the two stay equal, since the root cause is that they are edited independently and nothing tied them together. Verification: $ python -m build --wheel # in utils/hf Requires-Python: >=3.10.0 Requires-Dist: huggingface_hub==1.33.0.dev0 Signed-off-by: Sharvil Saxena * no need to add tests * Update utils/hf/setup.py --------- Signed-off-by: Sharvil Saxena Co-authored-by: célina --- utils/hf/setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/utils/hf/setup.py b/utils/hf/setup.py index 1f1ff687110..a1ac17bae4e 100644 --- a/utils/hf/setup.py +++ b/utils/hf/setup.py @@ -29,7 +29,7 @@ def get_version() -> str: url="https://github.com/huggingface/huggingface_hub", packages=["hf"], # dummy package to raise ImportError on import entry_points={"console_scripts": ["hf=huggingface_hub.cli.hf:main"]}, - python_requires=">=3.9.0", + python_requires=">=3.10.0", install_requires=install_requires, classifiers=[], ) From 94cf3927377ab81b79795e438ec9c11d3e2933f2 Mon Sep 17 00:00:00 2001 From: shaun smith <1936278+evalstate@users.noreply.github.com> Date: Tue, 22 Sep 2026 13:30:25 +0100 Subject: [PATCH 07/14] Remove dots from allowed characters in job labels. (#4962) --- src/huggingface_hub/hf_api.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/huggingface_hub/hf_api.py b/src/huggingface_hub/hf_api.py index 86cedbafdd8..a9c49e27115 100644 --- a/src/huggingface_hub/hf_api.py +++ b/src/huggingface_hub/hf_api.py @@ -12792,7 +12792,7 @@ def update_job_labels( labels (`dict[str, str]`): New labels to set on the job. Replaces all existing labels. Both keys and values must be max 100 characters and contain only - alphanumeric characters, dots, dashes, and underscores. + alphanumeric characters, dashes, and underscores. namespace (`str`, *optional*): The namespace where the Job is running. Defaults to the current user's namespace. @@ -13396,7 +13396,7 @@ def update_scheduled_job_labels( labels (`dict[str, str]`): New labels to set on the scheduled job. Replaces all existing labels. Both keys and values must be max 100 characters and contain only - alphanumeric characters, dots, dashes, and underscores. + alphanumeric characters, dashes, and underscores. namespace (`str`, *optional*): The namespace where the scheduled Job is. Defaults to the current user's namespace. From 8d4fba634e072bb0685a9ec4b9234c741227a2f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?c=C3=A9lina?= Date: Tue, 22 Sep 2026 15:37:31 +0200 Subject: [PATCH 08/14] [CLI] Honor `CLAUDE_CONFIG_DIR` in `hf skills add -g --claude` (#4957) * [CLI] Honor CLAUDE_CONFIG_DIR in hf skills add -g --claude * remove test --- docs/source/en/package_reference/cli.md | 3 ++- src/huggingface_hub/cli/skills.py | 3 ++- src/huggingface_hub/constants.py | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/source/en/package_reference/cli.md b/docs/source/en/package_reference/cli.md index efa62839ebb..afdf64ab971 100644 --- a/docs/source/en/package_reference/cli.md +++ b/docs/source/en/package_reference/cli.md @@ -4298,7 +4298,8 @@ Install a Hugging Face skill for an AI assistant. The default `hf-cli` skill is generated locally from the installed CLI version; other skills are downloaded from the Hugging Face marketplace. Default location is in the current directory (.agents/skills) or user-level (~/.agents/skills). -If `--claude` is specified, the skill is also symlinked into Claude's legacy skills directory. +If `--claude` is specified, the skill is also symlinked into Claude's legacy skills directory +(`.claude/skills` or `~/.claude/skills`, honoring `CLAUDE_CONFIG_DIR` when set). **Usage**: diff --git a/src/huggingface_hub/cli/skills.py b/src/huggingface_hub/cli/skills.py index 43ec80c6383..b4844fcfb7b 100644 --- a/src/huggingface_hub/cli/skills.py +++ b/src/huggingface_hub/cli/skills.py @@ -456,7 +456,8 @@ def skills_add( The default `hf-cli` skill is generated locally from the installed CLI version; other skills are downloaded from the Hugging Face marketplace. Default location is in the current directory (.agents/skills) or user-level (~/.agents/skills). - If `--claude` is specified, the skill is also symlinked into Claude's legacy skills directory. + If `--claude` is specified, the skill is also symlinked into Claude's legacy skills directory + (`.claude/skills` or `~/.claude/skills`, honoring `CLAUDE_CONFIG_DIR` when set). """ if dest is not None: if claude or global_: diff --git a/src/huggingface_hub/constants.py b/src/huggingface_hub/constants.py index 1e2f4c804af..61934410a3b 100644 --- a/src/huggingface_hub/constants.py +++ b/src/huggingface_hub/constants.py @@ -227,10 +227,11 @@ def list_files(repo_id: str): # Skills directories for AI agents: `.agents/skills` is read by most agents, `.claude/skills` by Claude Code. # Local = current project, global = user-level (see `hf skills add`). +# Claude Code's user-level directory defaults to `~/.claude` but can be relocated with `CLAUDE_CONFIG_DIR`. AGENTS_SKILLS_LOCAL_PATH = Path(".agents/skills") AGENTS_SKILLS_GLOBAL_PATH = Path("~/.agents/skills") CLAUDE_SKILLS_LOCAL_PATH = Path(".claude/skills") -CLAUDE_SKILLS_GLOBAL_PATH = Path("~/.claude/skills") +CLAUDE_SKILLS_GLOBAL_PATH = Path(os.environ.get("CLAUDE_CONFIG_DIR") or "~/.claude") / "skills" # Set to skip the CLI update check (PyPI query + "new version available" warning at startup). HF_HUB_DISABLE_UPDATE_CHECK = _is_true(os.environ.get("HF_HUB_DISABLE_UPDATE_CHECK")) From aa8742c947e4890dcdb59c4855c53536f4a7050c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?c=C3=A9lina?= Date: Tue, 22 Sep 2026 16:29:58 +0200 Subject: [PATCH 09/14] [CLI] Always install skills for Claude Code, deprecate --claude (#4967) * [CLI] Always install skills for Claude Code, deprecate --claude * show --claude as deprecated in help instead of hiding it * remove test --- README.md | 4 +- docs/source/en/guides/cli.md | 4 +- docs/source/en/package_reference/cli.md | 13 +++--- docs/source/en/quick-start.md | 4 +- src/huggingface_hub/cli/_skills.py | 8 ++-- src/huggingface_hub/cli/skills.py | 62 ++++++++++++++----------- src/huggingface_hub/cli/system.py | 4 +- tests/test_cli.py | 4 +- utils/installers/install.ps1 | 4 +- utils/installers/install.sh | 4 +- 10 files changed, 57 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index d626032c129..30ea5d20efc 100644 --- a/README.md +++ b/README.md @@ -102,10 +102,8 @@ The `huggingface_hub` library allows you to interact with the [Hugging Face Hub] The `hf` CLI is designed for people and coding agents alike: the same commands adapt their output when run by an agent. If you use Claude Code, Codex, Cursor, or another coding agent, install the `hf` CLI Skill — a command reference generated from your installed CLI: ```bash -# for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills` +# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills` hf skills add -# includes the above + Claude Code -hf skills add --claude ``` Learn more in the [Hugging Face CLI for AI agents guide](https://huggingface.co/docs/hub/agents-cli) and the [announcement blog post](https://huggingface.co/blog/hf-cli-for-agents). diff --git a/docs/source/en/guides/cli.md b/docs/source/en/guides/cli.md index 088808090e8..2f8094de1f3 100644 --- a/docs/source/en/guides/cli.md +++ b/docs/source/en/guides/cli.md @@ -13,10 +13,8 @@ The `huggingface_hub` Python package comes with a built-in CLI called `hf`. This > [!TIP] > Using the `hf` CLI with AI agents? Install the Skill and check out the [Hugging Face CLI for AI Agents](https://huggingface.co/docs/hub/agents-cli) guide. > ```bash -> # for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills` +> # works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills` > hf skills add -> # includes the above + Claude Code -> hf skills add --claude > ``` > The standalone installer installs it for you (see below), and `hf update` refreshes it. diff --git a/docs/source/en/package_reference/cli.md b/docs/source/en/package_reference/cli.md index afdf64ab971..7ab6a7d235f 100644 --- a/docs/source/en/package_reference/cli.md +++ b/docs/source/en/package_reference/cli.md @@ -4298,8 +4298,8 @@ Install a Hugging Face skill for an AI assistant. The default `hf-cli` skill is generated locally from the installed CLI version; other skills are downloaded from the Hugging Face marketplace. Default location is in the current directory (.agents/skills) or user-level (~/.agents/skills). -If `--claude` is specified, the skill is also symlinked into Claude's legacy skills directory -(`.claude/skills` or `~/.claude/skills`, honoring `CLAUDE_CONFIG_DIR` when set). +The skill is also symlinked into Claude Code's skills directory (`.claude/skills` or `~/.claude/skills`, +honoring `CLAUDE_CONFIG_DIR` when set), unless `--dest` is used. **Usage**: @@ -4313,7 +4313,7 @@ $ hf skills add [OPTIONS] [NAME] **Options**: -* `--claude`: Install for Claude. +* `--claude`: (Deprecated) No longer needed: skills are always installed for Claude Code too. * `-g, --global`: Install globally (user-level) instead of in the current project directory. * `--dest PATH`: Install into a custom destination (path to skills directory). * `--force`: Overwrite existing skills in the destination. @@ -4323,8 +4323,7 @@ Examples $ hf skills add $ hf skills add huggingface-gradio --dest=~/my-skills $ hf skills add --global - $ hf skills add --claude - $ hf skills add huggingface-gradio --claude --global + $ hf skills add huggingface-gradio --global Learn more Use `hf --help` for more information about a command. @@ -4385,7 +4384,7 @@ $ hf skills update [OPTIONS] [NAME] **Options**: -* `--claude`: Update skills installed for Claude. +* `--claude`: (Deprecated) No longer needed: skills are always installed for Claude Code too. * `-g, --global`: Use global skills directories instead of the current project. * `--dest PATH`: Update skills in a custom skills directory. * `--help`: Show this message and exit. @@ -4394,7 +4393,7 @@ Examples $ hf skills update $ hf skills update hf-cli $ hf skills update huggingface-gradio --dest=~/my-skills - $ hf skills update --claude + $ hf skills update -g Learn more Use `hf --help` for more information about a command. diff --git a/docs/source/en/quick-start.md b/docs/source/en/quick-start.md index 16d83562224..1effff2aeaa 100644 --- a/docs/source/en/quick-start.md +++ b/docs/source/en/quick-start.md @@ -24,10 +24,8 @@ For more details, check out the [installation](installation) guide. > The `huggingface_hub` also ships with a [`hf` CLI](./guides/cli) that lets you interact with the Hub directly from the terminal. > If you're using AI agents (Claude Code, Codex, Cursor, ...), install the Skill to let your agent use the CLI: > ```bash -> # for Codex, Cursor, OpenCode, Pi and other agents that load skills from `.agents/skills` +> # works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills` > hf skills add -> # includes the above + Claude Code -> hf skills add --claude > ``` > Check out the [Hugging Face CLI for AI Agents](https://huggingface.co/docs/hub/agents-cli) guide for more details. diff --git a/src/huggingface_hub/cli/_skills.py b/src/huggingface_hub/cli/_skills.py index c7296d1ccb3..f47d3c16ec8 100644 --- a/src/huggingface_hub/cli/_skills.py +++ b/src/huggingface_hub/cli/_skills.py @@ -356,21 +356,21 @@ def _check_skill_update() -> None: if any(tag in __version__ for tag in ["rc", "dev"]): return out.hint( - f"The `{DEFAULT_SKILL_ID}` skill is not installed. Run `hf skills add -g --claude`" + f"The `{DEFAULT_SKILL_ID}` skill is not installed. Run `hf skills add -g`" " to teach your AI agents how to use the `hf` CLI." ) return # Suggest the command matching where the outdated skill is installed (global takes precedence). if any(_is_skill_outdated(skill_dir) for skill_dir in global_dirs): - scope = "-g --claude" + scope = " -g" elif any(_is_skill_outdated(skill_dir) for skill_dir in local_dirs): - scope = "--claude" + scope = "" else: return out.hint( f"The installed `{DEFAULT_SKILL_ID}` skill was generated by another `hf` version." - f" Run `hf skills update {DEFAULT_SKILL_ID} {scope}` to refresh it." + f" Run `hf skills update {DEFAULT_SKILL_ID}{scope}` to refresh it." ) diff --git a/src/huggingface_hub/cli/skills.py b/src/huggingface_hub/cli/skills.py index b4844fcfb7b..c8f8e9e9195 100644 --- a/src/huggingface_hub/cli/skills.py +++ b/src/huggingface_hub/cli/skills.py @@ -330,6 +330,12 @@ def _install_to(skills_dir: Path, skill_name: str, force: bool) -> Path: raise CLIError(f"{exc}\nRe-run with --force to overwrite.") from exc +_CLAUDE_FLAG_DEPRECATED = ( + "`--claude` is deprecated and will be removed in a future release:" + " skills are always installed for Claude Code too." +) + + def _create_symlink(agent_skills_dir: Path, skill_name: str, central_skill_path: Path, force: bool) -> Path: """Create a relative symlink from agent directory to the central skill location.""" agent_skills_dir = agent_skills_dir.expanduser().resolve() @@ -347,20 +353,16 @@ def _create_symlink(agent_skills_dir: Path, skill_name: str, central_skill_path: return link_path -def _resolve_update_roots( - *, - claude: bool, - global_: bool, - dest: Path | None, -) -> list[Path]: +def _resolve_update_roots(*, global_: bool, dest: Path | None) -> list[Path]: if dest is not None: - if claude or global_: - raise CLIError("--dest cannot be combined with --claude or --global.") + if global_: + raise CLIError("--dest cannot be combined with --global.") return [dest.expanduser().resolve()] - roots: list[Path] = [constants.AGENTS_SKILLS_GLOBAL_PATH if global_ else constants.AGENTS_SKILLS_LOCAL_PATH] - if claude: - roots.append(constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH) + if global_: + roots = [constants.AGENTS_SKILLS_GLOBAL_PATH, constants.CLAUDE_SKILLS_GLOBAL_PATH] + else: + roots = [constants.AGENTS_SKILLS_LOCAL_PATH, constants.CLAUDE_SKILLS_LOCAL_PATH] return [root.expanduser().resolve() for root in roots] @@ -419,8 +421,7 @@ def skills_list( "hf skills add", "hf skills add huggingface-gradio --dest=~/my-skills", "hf skills add --global", - "hf skills add --claude", - "hf skills add huggingface-gradio --claude --global", + "hf skills add huggingface-gradio --global", ], ) def skills_add( @@ -428,7 +429,10 @@ def skills_add( str, Argument(help="Marketplace skill name.", show_default=False), ] = DEFAULT_SKILL_ID, - claude: Annotated[bool, Option("--claude", help="Install for Claude.")] = False, + claude: Annotated[ + bool, + Option("--claude", help="(Deprecated) No longer needed: skills are always installed for Claude Code too."), + ] = False, global_: Annotated[ bool, Option( @@ -456,25 +460,26 @@ def skills_add( The default `hf-cli` skill is generated locally from the installed CLI version; other skills are downloaded from the Hugging Face marketplace. Default location is in the current directory (.agents/skills) or user-level (~/.agents/skills). - If `--claude` is specified, the skill is also symlinked into Claude's legacy skills directory - (`.claude/skills` or `~/.claude/skills`, honoring `CLAUDE_CONFIG_DIR` when set). + The skill is also symlinked into Claude Code's skills directory (`.claude/skills` or `~/.claude/skills`, + honoring `CLAUDE_CONFIG_DIR` when set), unless `--dest` is used. """ + if claude: + out.warning(_CLAUDE_FLAG_DEPRECATED) if dest is not None: - if claude or global_: - raise CLIError("--dest cannot be combined with --claude or --global.") + if global_: + raise CLIError("--dest cannot be combined with --global.") skill_dest = _install_to(dest, name, force) print(f"Installed '{name}' to {skill_dest}") return - # Install to central location + # Install to central location, then expose it to Claude Code which only reads `.claude/skills` central_path = constants.AGENTS_SKILLS_GLOBAL_PATH if global_ else constants.AGENTS_SKILLS_LOCAL_PATH central_skill_path = _install_to(central_path, name, force) print(f"Installed '{name}' to central location: {central_skill_path}") - if claude: - agent_target = constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH - link_path = _create_symlink(agent_target, name, central_skill_path, force) - print(f"Created symlink: {link_path}" if link_path.is_symlink() else f"Copied '{name}' to {link_path}") + claude_path = constants.CLAUDE_SKILLS_GLOBAL_PATH if global_ else constants.CLAUDE_SKILLS_LOCAL_PATH + link_path = _create_symlink(claude_path, name, central_skill_path, force) + print(f"Created symlink: {link_path}" if link_path.is_symlink() else f"Copied '{name}' to {link_path}") @skills_cli.command( @@ -483,7 +488,7 @@ def skills_add( "hf skills update", "hf skills update hf-cli", "hf skills update huggingface-gradio --dest=~/my-skills", - "hf skills update --claude", + "hf skills update -g", ], ) def skills_update( @@ -491,7 +496,10 @@ def skills_update( str | None, Argument(help="Optional installed skill name to update.", show_default=False), ] = None, - claude: Annotated[bool, Option("--claude", help="Update skills installed for Claude.")] = False, + claude: Annotated[ + bool, + Option("--claude", help="(Deprecated) No longer needed: skills are always installed for Claude Code too."), + ] = False, global_: Annotated[ bool, Option( @@ -508,7 +516,9 @@ def skills_update( ] = None, ) -> None: """Update installed Hugging Face marketplace skills.""" - roots = _resolve_update_roots(claude=claude, global_=global_, dest=dest) + if claude: + out.warning(_CLAUDE_FLAG_DEPRECATED) + roots = _resolve_update_roots(global_=global_, dest=dest) results = _skills.update_skills(roots, selector=name, hf_cli_content=build_skill_md()) if not results: diff --git a/src/huggingface_hub/cli/system.py b/src/huggingface_hub/cli/system.py index ad7813e95c0..46a8bbd2f3a 100644 --- a/src/huggingface_hub/cli/system.py +++ b/src/huggingface_hub/cli/system.py @@ -71,14 +71,14 @@ def update() -> None: raise click.exceptions.Exit(code=returncode) if not skill_installed: - out.hint("Run `hf skills add -g --claude` to teach your AI agents how to use the `hf` CLI.") + out.hint("Run `hf skills add -g` to teach your AI agents how to use the `hf` CLI.") return # Refresh the globally installed skill so agents see the new command surface. Runs in a # subprocess: the skill is generated from the CLI code, which has just been replaced on disk # while this process still runs the previous version. out.text(f"Updating the `{DEFAULT_SKILL_ID}` skill...") - subprocess.call([*_hf_argv(), "skills", "update", DEFAULT_SKILL_ID, "-g", "--claude"]) + subprocess.call([*_hf_argv(), "skills", "update", DEFAULT_SKILL_ID, "-g"]) def _hf_argv() -> list[str]: diff --git a/tests/test_cli.py b/tests/test_cli.py index 5c249e614ba..97e452d8a32 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -5380,14 +5380,14 @@ def _write_global_skill(self, tmp_path: Path, content: str) -> Path: def test_hints_to_add_when_not_installed(self, capsys: pytest.CaptureFixture) -> None: with patch.object(_skills, "__version__", "1.0.0"): _skills.check_skill_update() - assert "hf skills add -g --claude" in capsys.readouterr().err + assert "hf skills add -g" in capsys.readouterr().err def test_hints_to_update_when_generated_by_another_version( self, tmp_path: Path, capsys: pytest.CaptureFixture ) -> None: self._write_global_skill(tmp_path, "Generated with `huggingface_hub v0.0.1`.") _skills.check_skill_update() - assert "hf skills update hf-cli -g --claude" in capsys.readouterr().err + assert "hf skills update hf-cli -g" in capsys.readouterr().err def test_silent_when_up_to_date_and_throttled_afterwards( self, tmp_path: Path, capsys: pytest.CaptureFixture diff --git a/utils/installers/install.ps1 b/utils/installers/install.ps1 index 9b9ab8a9c49..be355c3e1fa 100644 --- a/utils/installers/install.ps1 +++ b/utils/installers/install.ps1 @@ -349,9 +349,9 @@ function Install-Skill { Write-Log "Installing the hf-cli skill for AI agents..." $hfExecutable = Join-Path $BIN_DIR "hf.exe" - & $hfExecutable skills add hf-cli --global --claude --force + & $hfExecutable skills add hf-cli --global --force if (-not $?) { - Write-Log "Failed to install the hf-cli skill. Install it later with: hf skills add -g --claude" "WARNING" + Write-Log "Failed to install the hf-cli skill. Install it later with: hf skills add -g" "WARNING" return } Write-Log "The hf-cli skill was installed automatically so AI agents know how to use the hf CLI." diff --git a/utils/installers/install.sh b/utils/installers/install.sh index aad1a27621a..b21e61071c2 100755 --- a/utils/installers/install.sh +++ b/utils/installers/install.sh @@ -404,8 +404,8 @@ install_skill() { fi log_info "Installing the hf-cli skill for AI agents..." - if ! "$BIN_DIR/hf" skills add hf-cli --global --claude --force; then - log_warning "Failed to install the hf-cli skill. Install it later with: hf skills add -g --claude" + if ! "$BIN_DIR/hf" skills add hf-cli --global --force; then + log_warning "Failed to install the hf-cli skill. Install it later with: hf skills add -g" return fi log_info "The hf-cli skill was installed automatically so AI agents know how to use the hf CLI." From ce69fdb010b61260d5bf6345d6935c1df76fa36b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?c=C3=A9lina?= Date: Tue, 22 Sep 2026 17:08:57 +0200 Subject: [PATCH 10/14] [Buckets] Raise when a batch reports failed operations (#4954) * [Buckets] Raise when a batch reports failed operations * fix pickling of BucketBatchError * keep only the main test * Update src/huggingface_hub/hf_api.py Co-authored-by: Lucain * fix missing parenthesis * use a real test against staging * keep sending chunks after a failure * fold batch tests into one --------- Co-authored-by: Lucain --- docs/source/en/guides/buckets.md | 2 +- src/huggingface_hub/errors.py | 12 +++++ src/huggingface_hub/hf_api.py | 84 ++++++++++++++++++++------------ tests/test_buckets.py | 24 ++++++++- 4 files changed, 89 insertions(+), 33 deletions(-) diff --git a/docs/source/en/guides/buckets.md b/docs/source/en/guides/buckets.md index 7340296db97..b7c2dd106b4 100644 --- a/docs/source/en/guides/buckets.md +++ b/docs/source/en/guides/buckets.md @@ -421,7 +421,7 @@ You can also delete files while uploading others. ``` > [!WARNING] -> Calls to [`batch_bucket_files`] are non-transactional. If an error occurs during the process, some files may have been uploaded, copied, or deleted while others haven't. +> Calls to [`batch_bucket_files`] are non-transactional. If an error occurs during the process, some files may have been uploaded, copied, or deleted while others haven't. When the server reports that some operations failed, a [`BucketBatchError`] is raised with the failed paths on its `failures` attribute. ### Upload a single file with the CLI diff --git a/src/huggingface_hub/errors.py b/src/huggingface_hub/errors.py index 38f9d339be2..1ec42fbd8b1 100644 --- a/src/huggingface_hub/errors.py +++ b/src/huggingface_hub/errors.py @@ -280,6 +280,18 @@ class BucketNotFoundError(HfHubHTTPError): bucket_id: str | None = None +class BucketBatchError(HfHubHTTPError): + """ + Raised when the server reports that some operations of a bucket batch failed. + + Attributes: + failures (`list[dict[str, str]]`): + The failed operations as listed by the server, e.g. `[{"path": "config.json", "error": "..."}]`. + """ + + failures: list[dict[str, str]] = [] + + # JOB ERRORS diff --git a/src/huggingface_hub/hf_api.py b/src/huggingface_hub/hf_api.py index a9c49e27115..70148b3ddee 100644 --- a/src/huggingface_hub/hf_api.py +++ b/src/huggingface_hub/hf_api.py @@ -82,6 +82,7 @@ ) from .errors import ( BadRequestError, + BucketBatchError, EntryNotFoundError, FileDuplicationError, GatedRepoError, @@ -254,6 +255,7 @@ _BUCKET_PATHS_INFO_BATCH_SIZE = 1000 _BUCKET_BATCH_ADD_CHUNK_SIZE = 1000 _BUCKET_BATCH_DELETE_CHUNK_SIZE = 1000 +_BUCKET_BATCH_MAX_LISTED_FAILURES = 10 # in the error message; the full list is on `BucketBatchError.failures` # Regex used to match special revisions with "/" in them (see #1710) SPECIAL_REFS_REVISION_REGEX = re.compile( @@ -14347,7 +14349,7 @@ def _copy_to_bucket( *, token: str | bool | None = None, ) -> None: - from ._buckets import BucketFile, _BucketCopyFile + from ._buckets import BucketFile destination_bucket_id = destination.id destination_path = destination.path_in_repo @@ -14367,8 +14369,8 @@ def _copy_to_bucket( ) destination_is_directory = destination_exists_as_directory or destination_str.endswith("/") - all_adds: list[tuple[str, str]] = [] - all_copies: list[_BucketCopyFile] = [] + all_adds: list[tuple[str | Path | bytes, str]] = [] + all_copies: list[tuple[str, str, str, str]] = [] pending_downloads: list[tuple[str, str]] = [] def _resolve_target_path(src_file_path: str, src_root_path: str | None, is_single_file: bool) -> str: @@ -14382,21 +14384,9 @@ def _resolve_target_path(src_file_path: str, src_root_path: str | None, is_singl merge_contents, ) - def _build_copy_op( - target_path: str, xet_hash: str, size: int, source_repo_type: str, source_repo_id: str - ) -> _BucketCopyFile: - """Server-side copy by xet hash — no data transfer needed.""" - return _BucketCopyFile( - destination=target_path, - xet_hash=xet_hash, - source_repo_type=source_repo_type, - source_repo_id=source_repo_id, - size=size, - ) - def _add_repo_file(file: RepoFile, target_path: str) -> None: if file.xet_hash is not None: - all_copies.append(_build_copy_op(target_path, file.xet_hash, file.size, source.type, source.id)) + all_copies.append((source.type, source.id, file.xet_hash, target_path)) else: pending_downloads.append((file.path, target_path)) @@ -14407,9 +14397,7 @@ def _add_repo_file(file: RepoFile, target_path: str) -> None: if source_path_info: source_file = source_path_info[0] target_path = _resolve_target_path(source_file.path, None, is_single_file=True) - all_copies.append( - _build_copy_op(target_path, source_file.xet_hash, source_file.size, "bucket", source.id) - ) + all_copies.append(("bucket", source.id, source_file.xet_hash, target_path)) else: for item in self.list_bucket_tree(source.id, prefix=source_path or None, recursive=True, token=token): if not isinstance(item, BucketFile): @@ -14417,7 +14405,7 @@ def _add_repo_file(file: RepoFile, target_path: str) -> None: if source_path and not (item.path == source_path or item.path.startswith(source_path + "/")): continue target_path = _resolve_target_path(item.path, source_path or None, is_single_file=False) - all_copies.append(_build_copy_op(target_path, item.xet_hash, item.size, "bucket", source.id)) + all_copies.append(("bucket", source.id, item.xet_hash, target_path)) else: for file, target_path in self._iter_repo_files_for_copy( source, @@ -14457,13 +14445,7 @@ def _download_and_collect(item: tuple[str, str]) -> None: hf_thread_map(_download_and_collect, pending_downloads, desc="Downloading text files for copy") - # Send copies first (no upload needed), then adds (may need upload) - if all_copies: - for copy_chunk in chunk_iterable(all_copies, chunk_size=_BUCKET_BATCH_ADD_CHUNK_SIZE): - self._batch_bucket_files(destination_bucket_id, copy=list(copy_chunk), token=token) - if all_adds: - for add_chunk in chunk_iterable(all_adds, chunk_size=_BUCKET_BATCH_ADD_CHUNK_SIZE): - self._batch_bucket_files(destination_bucket_id, add=list(add_chunk), token=token) + self.batch_bucket_files(destination_bucket_id, add=all_adds, copy=all_copies, token=token) def _iter_repo_files_for_copy( self, @@ -14632,6 +14614,11 @@ def batch_bucket_files( https://huggingface.co/docs/huggingface_hub/quick-start#authentication). To disable authentication, pass `False`. + Raises: + [`~errors.BucketBatchError`]: + If the server reports that some operations failed. The error is raised once every operation has + been sent, so the other operations of the batch have been applied. + Example: ```python >>> from huggingface_hub import batch_bucket_files @@ -14683,20 +14670,36 @@ def batch_bucket_files( else: progress = None + # A failing chunk must not stop the others: collect the errors and raise once everything has been sent + errors: list[BucketBatchError] = [] + + def _send_chunk(**operations: Any) -> None: + try: + self._batch_bucket_files(bucket_id, token=token, **operations) + except BucketBatchError as error: + logger.warning(str(error)) + errors.append(error) + try: for copy_chunk in chunk_iterable(copy, chunk_size=_BUCKET_BATCH_ADD_CHUNK_SIZE): - self._batch_bucket_files(bucket_id, copy=list(copy_chunk), token=token) + _send_chunk(copy=list(copy_chunk)) for add_chunk in chunk_iterable(add, chunk_size=_BUCKET_BATCH_ADD_CHUNK_SIZE): - self._batch_bucket_files(bucket_id, add=list(add_chunk), token=token, _progress=progress) + _send_chunk(add=list(add_chunk), _progress=progress) for delete_chunk in chunk_iterable(delete, chunk_size=_BUCKET_BATCH_DELETE_CHUNK_SIZE): - self._batch_bucket_files(bucket_id, delete=list(delete_chunk), token=token) + _send_chunk(delete=list(delete_chunk)) finally: if progress is not None: progress.close() - return + if errors: + raise _bucket_batch_error( + bucket_id, + [failure for error in errors for failure in error.failures], + sent=len(add) + len(copy) + len(delete), + response=errors[-1].response, + ) def _batch_bucket_files( self, @@ -14847,6 +14850,11 @@ def _payload_as_ndjson() -> Iterable[bytes]: response = http_backoff( "POST", f"{self.endpoint}/api/buckets/{bucket_id}/batch", headers=headers, content=data ) + # Failed operations are listed in the body of a 200 (partial failure) or a 422 (all failed) + if response.status_code in (200, 422): + failures = response.json().get("failed", []) + if failures: + raise _bucket_batch_error(bucket_id, failures, sent=len(operations), response=response) hf_raise_for_status(response) @validate_hf_hub_args @@ -15163,6 +15171,20 @@ def sync_bucket( ) +def _bucket_batch_error( + bucket_id: str, failures: list[dict[str, str]], *, sent: int, response: httpx.Response +) -> BucketBatchError: + messages = [f" - {f['path']}: {f['error']}" for f in failures[:_BUCKET_BATCH_MAX_LISTED_FAILURES]] + if len(failures) > _BUCKET_BATCH_MAX_LISTED_FAILURES: + messages.append(f" - ... and {len(failures) - _BUCKET_BATCH_MAX_LISTED_FAILURES} more") + error = BucketBatchError( + f"Failed to apply {len(failures)} out of {sent} operation(s) on bucket '{bucket_id}':\n" + "\n".join(messages), + response=response, + ) + error.failures = failures + return error + + def _parse_revision_from_pr_url(pr_url: str) -> str: """Safely parse revision number from a PR url. diff --git a/tests/test_buckets.py b/tests/test_buckets.py index e34a9c51b7a..89775ad6c41 100644 --- a/tests/test_buckets.py +++ b/tests/test_buckets.py @@ -21,7 +21,7 @@ from huggingface_hub import HfApi from huggingface_hub._buckets import BucketFile, BucketInfo, SyncOperation, SyncPlan, _execute_plan from huggingface_hub._jobs_api import _derive_job_volume_name -from huggingface_hub.errors import BucketNotFoundError, EntryNotFoundError, HfHubHTTPError +from huggingface_hub.errors import BucketBatchError, BucketNotFoundError, EntryNotFoundError, HfHubHTTPError from .testing_constants import ENDPOINT_STAGING, ENTERPRISE_ORG, ENTERPRISE_TOKEN, OTHER_TOKEN, TOKEN, USER from .testing_utils import repo_name @@ -640,3 +640,25 @@ def test_execute_plan_rejects_path_traversal(tmp_path): with pytest.raises(ValueError, match="Invalid filename"): _execute_plan(plan, api) assert outside.exists() # not deleted + + +def test_batch_bucket_files_raises_on_failed_operations(api: HfApi, bucket_write: str, mocker): + api.batch_bucket_files(bucket_write, add=[(b"content", "file.txt")]) + xet_hash = next(iter(api.list_bucket_tree(bucket_write))).xet_hash + bogus_copy = ("bucket", bucket_write, "0" * 64, "bogus.txt") + + with pytest.raises(BucketBatchError) as exc_info: + api.batch_bucket_files(bucket_write, copy=[("bucket", bucket_write, xet_hash, "copy.txt"), bogus_copy]) + assert exc_info.value.response.status_code == 200 + assert [failure["path"] for failure in exc_info.value.failures] == ["bogus.txt"] + assert {file.path for file in api.list_bucket_tree(bucket_write)} == {"file.txt", "copy.txt"} + + with pytest.raises(BucketBatchError) as exc_info: + api.batch_bucket_files(bucket_write, copy=[bogus_copy]) + assert exc_info.value.response.status_code == 422 + + mocker.patch("huggingface_hub.hf_api._BUCKET_BATCH_ADD_CHUNK_SIZE", 1) # one request per operation + with pytest.raises(BucketBatchError) as exc_info: + api.batch_bucket_files(bucket_write, copy=[bogus_copy, ("bucket", bucket_write, xet_hash, "copy2.txt")]) + assert [failure["path"] for failure in exc_info.value.failures] == ["bogus.txt"] + assert {file.path for file in api.list_bucket_tree(bucket_write)} == {"file.txt", "copy.txt", "copy2.txt"} From 0f88f3220035c590c30594faec5cc92953bd4611 Mon Sep 17 00:00:00 2001 From: Lucain Date: Wed, 23 Sep 2026 12:26:22 +0200 Subject: [PATCH 11/14] [Download] Extend tmp .incomplete path on Windows when too long (#4978) Co-authored-by: Claude Opus 5.5 (1M context) --- src/huggingface_hub/file_download.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/huggingface_hub/file_download.py b/src/huggingface_hub/file_download.py index 2d149483c8b..2658100ce16 100644 --- a/src/huggingface_hub/file_download.py +++ b/src/huggingface_hub/file_download.py @@ -1999,7 +1999,9 @@ def _download_to_tmp_and_move( # process, a broken lock costs only duplicated bandwidth: each process downloads the full # file and atomically renames it to the final destination. # See https://github.com/huggingface/huggingface_hub/pull/4228. + # Re-check the length on Windows: the suffix can push a path just under the limit above MAX_PATH. tmp_path = incomplete_path.with_name(f"{incomplete_path.stem}.{uuid.uuid4().hex[:8]}.incomplete") + tmp_path = Path(as_extended_path(tmp_path)) try: with tmp_path.open("wb") as f: logger.debug(f"Downloading '{filename}' to '{tmp_path}'") From 7532272aa412d9bc0751480b6841320c19875c20 Mon Sep 17 00:00:00 2001 From: Daniel van Strien Date: Wed, 23 Sep 2026 12:47:57 +0100 Subject: [PATCH 12/14] Fix HfFileSystem.get_file with a bare local filename (#4981) `os.path.dirname("file.txt")` is "", and `os.makedirs("")` raises FileNotFoundError. Fall back to the current directory, matching fsspec's base `get_file` and gcsfs (fsspec/gcsfs#618). Co-authored-by: Claude Opus 5.5 (1M context) --- src/huggingface_hub/hf_file_system.py | 2 +- tests/test_hf_file_system.py | 12 ++++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/src/huggingface_hub/hf_file_system.py b/src/huggingface_hub/hf_file_system.py index 18121141f5e..ae3bbccf1ff 100644 --- a/src/huggingface_hub/hf_file_system.py +++ b/src/huggingface_hub/hf_file_system.py @@ -1117,7 +1117,7 @@ def get_file(self, rpath, lpath=None, callback=_DEFAULT_CALLBACK, outfile=None, os.makedirs(lpath, exist_ok=True) return None else: - os.makedirs(os.path.dirname(lpath), exist_ok=True) + os.makedirs(os.path.dirname(lpath) or os.curdir, exist_ok=True) outfile = open(lpath, "wb") close_file = True initial_pos = outfile.tell() diff --git a/tests/test_hf_file_system.py b/tests/test_hf_file_system.py index 55940e56ef8..a67deda3bf9 100644 --- a/tests/test_hf_file_system.py +++ b/tests/test_hf_file_system.py @@ -360,6 +360,18 @@ def test_get_file_with_temporary_folder(self): with open(temp_file, "rb") as f: assert f.read() == b"dummy text data" + def test_get_file_with_bare_filename(self): + # Test passing a bare filename works => downloads to the current working directory + cwd = os.getcwd() + with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as temp_dir: + os.chdir(temp_dir) + try: + self.hffs.get_file(self.text_file, "temp_file.txt") + with open(os.path.join(temp_dir, "temp_file.txt"), "rb") as f: + assert f.read() == b"dummy text data" + finally: + os.chdir(cwd) + def test_get_file_with_kwargs(self): # If custom kwargs are passed, the function should still work but defaults to base implementation with patch.object(hf_file_system, "http_get") as mock: From da5e2441d56a1967db68833fccd2af0679049d57 Mon Sep 17 00:00:00 2001 From: "hf-security-analysis[bot]" <265538906+hf-security-analysis[bot]@users.noreply.github.com> Date: Wed, 23 Sep 2026 14:39:02 +0200 Subject: [PATCH 13/14] Scope GITHUB_TOKEN permissions per job (#4982) A job with no `permissions:` block inherits whatever the repository hands out. Each block added here grants what that job's own steps need and nothing more. Co-authored-by: hf-security-analysis[bot] <265538906+hf-security-analysis[bot]@users.noreply.github.com> --- .github/workflows/check-installers.yml | 8 ++++++-- .github/workflows/model_card_consistency_reminder.yml | 3 +++ .github/workflows/python-quality.yml | 4 ++++ .github/workflows/python-tests.yml | 8 ++++++++ .github/workflows/release.yml | 2 ++ .github/workflows/style-bot-action.yml | 4 ++++ .github/workflows/trufflehog.yml | 4 ++++ .github/workflows/update-inference-types.yaml | 4 ++++ 8 files changed, 35 insertions(+), 2 deletions(-) diff --git a/.github/workflows/check-installers.yml b/.github/workflows/check-installers.yml index f90626373fc..852cc705d44 100644 --- a/.github/workflows/check-installers.yml +++ b/.github/workflows/check-installers.yml @@ -13,11 +13,13 @@ on: - ".github/workflows/check-installers.yml" workflow_dispatch: {} -permissions: - contents: read + +permissions: {} jobs: linux-installer: + permissions: + contents: read runs-on: ubuntu-latest steps: - name: Checkout repository @@ -61,6 +63,8 @@ jobs: rm -rf "$HF_TEST_ROOT" windows-installer: + permissions: + contents: read runs-on: windows-latest steps: - name: Checkout repository diff --git a/.github/workflows/model_card_consistency_reminder.yml b/.github/workflows/model_card_consistency_reminder.yml index a323890a5ee..846d3a958f5 100644 --- a/.github/workflows/model_card_consistency_reminder.yml +++ b/.github/workflows/model_card_consistency_reminder.yml @@ -7,8 +7,11 @@ on: - src/huggingface_hub/templates/modelcard_template.md - src/huggingface_hub/templates/datasetcard_template.md +permissions: {} + jobs: comment: + permissions: {} runs-on: ubuntu-latest steps: - name: Create GitHub App token diff --git a/.github/workflows/python-quality.yml b/.github/workflows/python-quality.yml index cf4fba51e1c..0fcf5528193 100644 --- a/.github/workflows/python-quality.yml +++ b/.github/workflows/python-quality.yml @@ -13,8 +13,12 @@ on: - "js/**" - "api-inference-community/**" +permissions: {} + jobs: check_code_quality: + permissions: + contents: read runs-on: ubuntu-latest env: UV_HTTP_TIMEOUT: 600 # max 10min to install deps diff --git a/.github/workflows/python-tests.yml b/.github/workflows/python-tests.yml index a5f038288f2..3bc497517aa 100644 --- a/.github/workflows/python-tests.yml +++ b/.github/workflows/python-tests.yml @@ -17,8 +17,12 @@ concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true +permissions: {} + jobs: check-imports: + permissions: + contents: read # Catch missing dependencies: install only base requirements and verify all public imports work. runs-on: ubuntu-latest steps: @@ -38,6 +42,8 @@ jobs: python utils/check_imports.py build-ubuntu: + permissions: + contents: read runs-on: group: aws-general-8-plus # A healthy full-suite job takes ~20min. Anything much longer means something is stuck: fail fast instead of @@ -157,6 +163,8 @@ jobs: verbose: true build-windows: + permissions: + contents: read # (almost) Duplicate config compared to `build-ubuntu` but running on Windows. # Please make sure to keep it updated as well. runs-on: windows-latest diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2e04d863c46..0cb9176bf66 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -58,6 +58,7 @@ on: - minor-release - patch-release + permissions: {} jobs: @@ -1269,6 +1270,7 @@ jobs: # 9. SLACK — final status update # ============================================================ slack-complete: + permissions: {} needs: [prepare, publish-pypi, publish-hf-cli, release-notes, slack-message, archive-release-notes, test-downstream, post-release, sync-hf-cli-skill, notify-prs] if: ${{ always() && needs.prepare.outputs.message_ts }} runs-on: ubuntu-latest diff --git a/.github/workflows/style-bot-action.yml b/.github/workflows/style-bot-action.yml index 2064fcf2a28..855e8623696 100644 --- a/.github/workflows/style-bot-action.yml +++ b/.github/workflows/style-bot-action.yml @@ -32,8 +32,12 @@ on: required: true description: "GitHub App private key used to generate a short-lived token" +permissions: {} + jobs: check-permissions: + permissions: + contents: read if: > (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@bot /style') && diff --git a/.github/workflows/trufflehog.yml b/.github/workflows/trufflehog.yml index d619ad83d66..6f144ce1ee6 100644 --- a/.github/workflows/trufflehog.yml +++ b/.github/workflows/trufflehog.yml @@ -3,8 +3,12 @@ on: name: Secret Leaks +permissions: {} + jobs: trufflehog: + permissions: + contents: read runs-on: ubuntu-latest steps: - name: Checkout code diff --git a/.github/workflows/update-inference-types.yaml b/.github/workflows/update-inference-types.yaml index 3b0c191e03f..c18dbb5801f 100644 --- a/.github/workflows/update-inference-types.yaml +++ b/.github/workflows/update-inference-types.yaml @@ -9,8 +9,12 @@ concurrency: group: update-inference-types cancel-in-progress: true +permissions: {} + jobs: pull_request: + permissions: + contents: read runs-on: ubuntu-latest steps: # Setup Python From 1e0c30576b4026155aaf5cd3a12aacecec4e6352 Mon Sep 17 00:00:00 2001 From: Corentin REGAL Date: Wed, 23 Sep 2026 16:17:18 +0200 Subject: [PATCH 14/14] Send PrivateLink config under privateService in create_inference_endpoint (#4966) * Send PrivateLink config under privateService in create_inference_endpoint * [Inference] Keep account_id compatible for endpoint creation * [Inference] Remove account_id compatibility test --------- Co-authored-by: Lucain Pouget --- src/huggingface_hub/_inference_endpoints.py | 2 +- src/huggingface_hub/hf_api.py | 26 +++++++++++++++++++-- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/src/huggingface_hub/_inference_endpoints.py b/src/huggingface_hub/_inference_endpoints.py index f5b766939bc..94562166303 100644 --- a/src/huggingface_hub/_inference_endpoints.py +++ b/src/huggingface_hub/_inference_endpoints.py @@ -157,7 +157,7 @@ class InferenceEndpoint: >>> endpoint.status 'running' >>> endpoint.url - 'https://my-text-to-image.region.vendor.endpoints.huggingface.cloud' + 'https://68a0f3b5c6ee5c9dcc0e0a01.endpoints.huggingface.cloud' # Run inference >>> endpoint.client.text_to_image(...) diff --git a/src/huggingface_hub/hf_api.py b/src/huggingface_hub/hf_api.py index 70148b3ddee..ba6007808f3 100644 --- a/src/huggingface_hub/hf_api.py +++ b/src/huggingface_hub/hf_api.py @@ -9401,6 +9401,8 @@ def create_inference_endpoint( region: str, vendor: str, account_id: str | None = None, + private_link_account_id: str | None = None, + private_link_region: str | None = None, min_replica: int = 1, max_replica: int = 1, scaling_metric: InferenceEndpointScalingMetric | None = None, @@ -9446,7 +9448,14 @@ def create_inference_endpoint( vendor (`str`): The cloud provider or vendor where the Inference Endpoint will be hosted (e.g. `"aws"`). account_id (`str`, *optional*): - The account ID used to link a VPC to a private Inference Endpoint (if applicable). + Deprecated and ignored. Use `private_link_account_id` and `private_link_region` to configure + AWS PrivateLink. + private_link_account_id (`str`, *optional*): + The AWS account ID allowed to reach the Inference Endpoint through AWS PrivateLink. Requires + `private_link_region`. + private_link_region (`str`, *optional*): + The AWS region of the PrivateLink entry point (`"us-east-1"` or `"eu-west-1"`), where the VPC + endpoint of `private_link_account_id` will connect. Independent of the compute `region` and `vendor`. min_replica (`int`, *optional*): The minimum number of replicas (instances) to keep running for the Inference Endpoint. To enable scaling to zero, set this value to 0 and adjust `scale_to_zero_timeout` accordingly. Defaults to 1. @@ -9588,6 +9597,13 @@ def create_inference_endpoint( ``` """ + if account_id is not None: + warnings.warn( + "`account_id` has been ignored. Use `private_link_account_id` and `private_link_region` to configure" + " AWS PrivateLink.", + FutureWarning, + ) + namespace = namespace or self._get_namespace(token=token) if type == InferenceEndpointType.PROTECTED: @@ -9612,7 +9628,6 @@ def create_inference_endpoint( ) payload: dict = { - "accountId": account_id, "compute": { "accelerator": accelerator, "instanceSize": instance_size, @@ -9636,6 +9651,13 @@ def create_inference_endpoint( }, "type": type, } + if private_link_account_id is not None: + if private_link_region is None: + raise ValueError( + "`private_link_region` is required with `private_link_account_id`: the AWS region of the" + " PrivateLink entry point, 'us-east-1' or 'eu-west-1'." + ) + payload["privateService"] = {"accountId": private_link_account_id, "region": private_link_region} if scaling_metric: payload["compute"]["scaling"]["measure"] = {scaling_metric: scaling_threshold} # type: ignore model_payload: dict[str, Any] = payload["model"]