Upload a Model or Dataset with the hf CLI

Publishing to the Hub is three commands: log in, create the repo, push the files. The hf CLI (from huggingface_hub) handles all three, and the same work has a Python equivalent for scripts.

1. Log in

hf auth login

Paste a token that has write scope, created in your Hugging Face settings. In CI pass it directly: hf auth login --token $HF_TOKEN --add-to-git-credential.

2. Create the repo

hf repos create my-cool-model

Creates your-username/my-cool-model. Add --repo-type dataset for a dataset and --private to keep it unlisted:

hf repos create my-cool-dataset --repo-type dataset --private

The subcommand is repos (plural). You can skip this step, since hf upload creates a missing repo, but creating it first lets you set privacy before any file lands.

3. Upload a file or a folder

hf upload my-cool-model ./model.safetensors

Uploads one file to the repo root. The argument order is hf upload [repo_id] [local_path] [path_in_repo]; drop the third to keep the filename. For a whole folder with filtering:

hf upload my-cool-model ./checkpoints . --include "*.safetensors" --exclude "*.bin" --commit-message "Add fp16 weights"

Uploads only the safetensors files from ./checkpoints into the repo root under one commit. Add --repo-type dataset or --repo-type space for those repo types.

4. Add a README card

The repo README.md renders as the card. A minimal one needs a YAML header:

---
license: apache-2.0
tags:
  - text-generation
base_model: meta-llama/Llama-3.1-8B
---

license, tags and base_model drive discovery and filtering on the Hub; base_model marks the repo as a derivative (a fine-tune or quant) of the original.

5. Handle large files

You do nothing special. Large binaries — safetensors, GGUF, Parquet — are tracked automatically with pointer files and stored on the Hub’s Xet backend (Git LFS is still supported as legacy). The commands above push them like any text file. Very large single files can be rejected; check the current limits on Storage backends rather than assuming a number.

6. Do it from Python

from huggingface_hub import HfApi, create_repo
create_repo("my-cool-model", exist_ok=True)
HfApi().upload_folder(
    folder_path="./checkpoints",
    repo_id="your-username/my-cool-model",
    repo_type="model",
    allow_patterns="*.safetensors",
)

Same result as step 3, scriptable. upload_folder takes allow_patterns / ignore_patterns (the API names for --include / --exclude).

If it fails:

401 Unauthorized — not logged in, or your token is read-only. Re-run hf auth login with a write token.
“Repository Not Found” — wrong namespace. Use your-username/name or an org you can write to, not a bare name you do not own.
“Your push was rejected” (too large) — a single file exceeds the Hub limit. Shard it, or check Storage backends.

Next: download models with the hf CLI · choose a GGUF quantization.