[Buckets] Add search param to list_buckets

alexpouliquen · alexpouliquen · commit 79ffc3add0f8 · 2026-04-21T16:43:48.000+02:00
diff --git a/docs/source/en/guides/buckets.md b/docs/source/en/guides/buckets.md
@@ -128,6 +128,16 @@ username/logs                321.8 MB        2000 2026-02-13
 
 # List buckets in a specific namespace
 >>> hf buckets ls huggingface
+
+# Filter buckets by name
+>>> hf buckets list --search "checkpoint"
+```
+
+You can also filter buckets by name using `search`:
+
+```py
+>>> for bucket in list_buckets(search="checkpoint"):
+...     print(bucket.id)
 ```
 
 You can use the `--quiet` and `--format json` options to get different output format. This is particularly interesting if you want to pipe the output to another tool like `grep` or `jq`.
diff --git a/docs/source/en/guides/cli.md b/docs/source/en/guides/cli.md
@@ -574,6 +574,9 @@ username/logs                321.8 MB        2000 2026-02-13
 
 # List buckets in a specific namespace
 >>> hf buckets ls my-org
+
+# Filter buckets by name
+>>> hf buckets list --search "checkpoint"
 ```
 
 To get detailed information about a specific bucket (returned as JSON), use `hf buckets info`:
diff --git a/docs/source/en/package_reference/cli.md b/docs/source/en/package_reference/cli.md
@@ -399,6 +399,7 @@ $ hf buckets list [OPTIONS] [ARGUMENT]
 * `-h, --human-readable`: Show sizes in human readable format.
 * `--tree`: List files in tree format (only for listing files).
 * `-R, --recursive`: List files recursively (only for listing files).
+* `--search TEXT`: Search query.
 * `--format [table|json]`: Output format (table or json).  [default: table]
 * `-q, --quiet`: Print only IDs (one per line).
 * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
@@ -407,6 +408,7 @@ $ hf buckets list [OPTIONS] [ARGUMENT]
 Examples
   $ hf buckets list
   $ hf buckets list huggingface
+  $ hf buckets list --search "my-prefix"
   $ hf buckets list user/my-bucket
   $ hf buckets list user/my-bucket -R
   $ hf buckets list user/my-bucket -h
diff --git a/src/huggingface_hub/cli/buckets.py b/src/huggingface_hub/cli/buckets.py
@@ -43,6 +43,7 @@
     FormatOpt,
     OutputFormat,
     QuietOpt,
+    SearchOpt,
     TokenOpt,
     api_object_to_dict,
     get_hf_api,
@@ -283,6 +284,7 @@ def _is_bucket_id(argument: str) -> bool:
     examples=[
         "hf buckets list",
         "hf buckets list huggingface",
+        'hf buckets list --search "my-prefix"',
         "hf buckets list user/my-bucket",
         "hf buckets list user/my-bucket -R",
         "hf buckets list user/my-bucket -h",
@@ -325,6 +327,7 @@ def list_cmd(
             help="List files recursively (only for listing files).",
         ),
     ] = False,
+    search: SearchOpt = None,
     format: FormatOpt = OutputFormat.table,
     quiet: QuietOpt = False,
     token: TokenOpt = None,
@@ -338,6 +341,8 @@ def list_cmd(
     is_file_mode = argument is not None and _is_bucket_id(argument)
 
     if is_file_mode:
+        if search is not None:
+            raise typer.BadParameter("Cannot use --search when listing files.")
         _list_files(
             argument=argument,  # type: ignore
             human_readable=human_readable,
@@ -350,6 +355,7 @@ def list_cmd(
     else:
         _list_buckets(
             namespace=argument,
+            search=search,
             human_readable=human_readable,
             as_tree=as_tree,
             recursive=recursive,
@@ -361,6 +367,7 @@ def list_cmd(
 
 def _list_buckets(
     namespace: str | None,
+    search: str | None,
     human_readable: bool,
     as_tree: bool,
     recursive: bool,
@@ -382,7 +389,7 @@ def _list_buckets(
         namespace = namespace.rstrip("/")
 
     api = get_hf_api(token=token)
-    results = [api_object_to_dict(bucket) for bucket in api.list_buckets(namespace=namespace)]
+    results = [api_object_to_dict(bucket) for bucket in api.list_buckets(namespace=namespace, search=search)]
 
     if not results:
         if not quiet and format != OutputFormat.json:
diff --git a/src/huggingface_hub/hf_api.py b/src/huggingface_hub/hf_api.py
@@ -12523,13 +12523,16 @@ def list_buckets(
         self,
         namespace: str | None = None,
         *,
+        search: str | None = None,
         token: bool | str | None = None,
     ) -> Iterable[BucketInfo]:
         """List buckets on the Hub under a certain namespace.
 
         Args:
             namespace (`str`, *optional*):
                 List buckets under this namespace (user or organization). Defaults to listing user's buckets.
+            search (`str`, *optional*):
+                A search string to filter bucket names.
             token (`bool` or `str`, *optional*):
                 A valid user access token (string). Defaults to the locally saved
                 token, which is the recommended method for authentication (see
@@ -12547,12 +12550,18 @@ def list_buckets(
 
             >>> for bucket in list_buckets(namespace="huggingface"): # lists buckets in the "huggingface" organization
             ...     print(bucket)
+
+            >>> for bucket in list_buckets(search="my-prefix"): # filter buckets by name
+            ...     print(bucket)
             ```
         """
         if namespace is None:
             namespace = "me"
+        params: dict[str, Any] = {}
+        if search is not None:
+            params["search"] = search
         for item in paginate(
-            f"{self.endpoint}/api/buckets/{namespace}", params={}, headers=self._build_hf_headers(token=token)
+            f"{self.endpoint}/api/buckets/{namespace}", params=params, headers=self._build_hf_headers(token=token)
         ):
             yield BucketInfo(**item)
 
diff --git a/tests/test_buckets_cli.py b/tests/test_buckets_cli.py
@@ -506,6 +506,13 @@ def test_bucket_list_error_recursive_with_namespace():
     assert "Cannot use --recursive when listing buckets" in result.output
 
 
+def test_bucket_list_error_search_with_files(tree_bucket: str):
+    """Cannot use --search when listing files."""
+    result = cli(f"hf buckets list {tree_bucket} --search foo")
+    assert result.exit_code != 0
+    assert "Cannot use --search when listing files" in result.output
+
+
 # =============================================================================
 # List files
 # =============================================================================
