The `huggingface-cli upload` command is used to upload files or entire folders to a repository on the Hugging Face Hub. This command is essential for users who want to contribute models, datasets, or Spaces, or update existing repositories directly from their command line.
huggingface-cli upload [OPTIONS] <repo-id> <path-to-local-file-or-folder> [path-in-repo]- `<repo-id>`: The ID of the repository on the Hugging Face Hub. This typically follows the format `your-username/your-repo-name` for user repositories, or `organization/repo-name` for organization repositories.
- `<path-to-local-file-or-folder>`: The local path to the file or folder you want to upload. If it's a folder, all its contents will be uploaded.
- `[path-in-repo]`: (Optional) The target path within the repository where the file(s) or folder should be placed. If not provided, files/folders are placed at the root of the repository.
- `--repo-type {model, dataset, space}`: Specifies the type of the repository. Defaults to `model`. Ensure this matches the type of repository you are uploading to or creating.
- `--revision <branch_name_or_commit_id>`: The specific branch or commit ID to push to. Defaults to `main`. If the branch does not exist, it will be created.
- `--commit-message <message>`: A custom commit message for the upload. If not provided, a default message like `Upload file(s) with huggingface_hub` will be used.
- `--token <hf_token>`: Your Hugging Face API token. If not provided, the command will use the token stored locally from `huggingface-cli login`.
- `--private`: (When creating a new repository) Makes the repository private. This option is only effective if the repository does not already exist.
- `--delete-obsolete-files`: When uploading a local folder, if this option is set, any files in the remote repository that are *not* present in the local folder will be deleted. Use with caution, as it can remove files from your repository.
- `--skip-lfs-ptr`: Skip LFS pointer files when creating a new Git LFS file. This is useful if you manually managed LFS for large files.
Before running any `upload` command, ensure you are logged in to the Hugging Face CLI:
huggingface-cli login1. **Uploading a single file to the root of a model repository:**
huggingface-cli upload your-username/my-awesome-model ./model.safetensors*Explanation*: This uploads the file `model.safetensors` from the current directory to the root of the `my-awesome-model` repository under `your-username`.
2. **Uploading a file to a specific subdirectory within a dataset repository:**
huggingface-cli upload your-username/my-dataset ./data.csv data/*Explanation*: This uploads `data.csv` to the `data/` folder inside the `my-dataset` repository. The `--repo-type` is inferred as `model` by default, but it's good practice to specify it if it's a dataset.
huggingface-cli upload --repo-type dataset your-username/my-dataset ./data.csv data/3. **Uploading an entire folder to a Space repository, creating a new branch:**
huggingface-cli upload --repo-type space --revision development your-username/my-gradio-space ./my-app-folder*Explanation*: This uploads the entire contents of `./my-app-folder` to the root of the `my-gradio-space` repository, creating and pushing to a new branch named `development`. If `development` already exists, it will push to that branch.
4. **Uploading a folder and synchronizing (deleting remote obsolete files):**
huggingface-cli upload --repo-type model --delete-obsolete-files your-username/my-model-updates ./updated-model-files*Explanation*: This uploads the contents of `./updated-model-files` to `my-model-updates`. Any files previously in the `my-model-updates` repository that are *not* present in `./updated-model-files` will be deleted from the remote repository.
5. **Uploading with a custom commit message:**
huggingface-cli upload --commit-message "Add initial training script" your-username/my-project ./train.py*Explanation*: Uploads `train.py` with a custom commit message that is more descriptive than the default.
* **Authentication**: You must be logged in via `huggingface-cli login` or provide a `--token` for the command to succeed.
* **Repository Existence**: If the repository specified by `<repo-id>` does not exist, the `upload` command might attempt to create it, especially when uploading to your personal namespace. For organizations, you generally need to create the repository first.
* **Large Files**: Hugging Face Hub uses Git LFS (Large File Storage) for files exceeding a certain size. The CLI handles this automatically, but for very large datasets or models, ensure your Git LFS setup is correct if you encounter issues.
* **Permissions**: Ensure you have the necessary write permissions for the target repository.