feat: add hf buckets import command for S3-to-HF bucket ingestion

docs/source/en/package_reference/cli.md

@@ -211,6 +211,7 @@ $ hf buckets [OPTIONS] COMMAND [ARGS]...
 * `cp`: Copy a single file to or from a bucket.
 * `create`: Create a new bucket.
 * `delete`: Delete a bucket.
+* `import`: Import files from an S3 bucket into a...
 * `info`: Get info about a bucket.
 * `list`: List buckets or files in a bucket. [alias: ls]
 * `move`: Move (rename) a bucket to a new name or...
@@ -322,6 +323,49 @@ Learn more
   Read the documentation at https://huggingface.co/docs/huggingface_hub/en/guides/cli
 
 
+### `hf buckets import`
+
+Import files from an S3 bucket into a Hugging Face bucket.
+
+Data is streamed from S3 through the local machine and re-uploaded to HF.
+Requires the `s3fs` package (`pip install s3fs`). AWS credentials are resolved
+by the standard boto/botocore chain (env vars, ~/.aws/credentials, instance profiles, etc.).
+
+**Usage**:
+
+```console
+$ hf buckets import [OPTIONS] SOURCE DEST
+```
+
+**Arguments**:
+
+* `SOURCE`: S3 source URI (e.g. s3://my-bucket or s3://my-bucket/prefix/).  [required]
+* `DEST`: HF bucket destination (e.g. hf://buckets/namespace/bucket-name or hf://buckets/namespace/bucket-name/prefix).  [required]
+
+**Options**:
+
+* `--dry-run`: List files that would be imported without actually transferring.
+* `--include TEXT`: Include only files matching pattern (can specify multiple).
+* `--exclude TEXT`: Exclude files matching pattern (can specify multiple).
+* `-w, --workers INTEGER`: Number of parallel S3 download threads.  [default: 4]
+* `--batch-size INTEGER`: Number of files per upload batch.  [default: 50]
+* `-v, --verbose`: Show per-file transfer details.
+* `-q, --quiet`: Print only IDs (one per line).
+* `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens.
+* `--help`: Show this message and exit.
+
+Examples
+  $ hf buckets import s3://my-data-bucket hf://buckets/user/my-bucket
+  $ hf buckets import s3://my-data-bucket/prefix/ hf://buckets/user/my-bucket/dest-prefix
+  $ hf buckets import s3://my-data-bucket hf://buckets/user/my-bucket --dry-run
+  $ hf buckets import s3://my-data-bucket hf://buckets/user/my-bucket --include "*.parquet"
+  $ hf buckets import s3://my-data-bucket hf://buckets/user/my-bucket --exclude "*.tmp" --workers 8
+
+Learn more
+  Use `hf <command> --help` for more information about a command.
+  Read the documentation at https://huggingface.co/docs/huggingface_hub/en/guides/cli
+
+
 ### `hf buckets info`
 
 Get info about a bucket.

setup.py

@@ -51,6 +51,8 @@ def get_version() -> str:
 
 extras["mcp"] = ["mcp>=1.8.0"]
 
+extras["s3"] = ["s3fs"]
+
 extras["testing"] = (
     extras["oauth"]
     + [

src/huggingface_hub/__init__.py

@@ -58,8 +58,10 @@
         "BucketFolder",
         "BucketInfo",
         "BucketUrl",
+        "ImportStats",
         "SyncOperation",
         "SyncPlan",
+        "import_from_s3",
     ],
     "_commit_scheduler": [
         "CommitScheduler",
@@ -741,6 +743,7 @@
     "ImageToVideoOutput",
     "ImageToVideoParameters",
     "ImageToVideoTargetSize",
+    "ImportStats",
     "InferenceClient",
     "InferenceEndpoint",
     "InferenceEndpointError",
@@ -974,6 +977,7 @@
     "hf_hub_url",
     "hf_raise_for_status",
     "hffs",
+    "import_from_s3",
     "inspect_job",
     "inspect_scheduled_job",
     "interpreter_login",
@@ -1184,8 +1188,10 @@ def __dir__():
         BucketFolder,  # noqa: F401
         BucketInfo,  # noqa: F401
         BucketUrl,  # noqa: F401
+        ImportStats,  # noqa: F401
         SyncOperation,  # noqa: F401
         SyncPlan,  # noqa: F401
+        import_from_s3,  # noqa: F401
     )
     from ._commit_scheduler import CommitScheduler  # noqa: F401
     from ._eval_results import (