# Upload a Model or Dataset with the hf CLI

> Log in, create a repo with hf repos create, push files with hf upload and include/exclude, write a minimal README card, and do the same from Python.

- Canonical: https://guides-ai.com/guides/hugging-face-upload-model-or-dataset/
- Plate 16.09 · Topic: Hugging Face (https://guides-ai.com/topics/huggingface/)
- Published: 12 Oct 2026 · 3 min read
- Source site: guides-ai — https://guides-ai.com/

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

```bash
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

```bash
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:

```bash
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

```bash
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:

```bash
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:

```yaml
---
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](/glossary/#fine-tuning) or quant) of the original.

## 5. Handle large files

You do nothing special. Large binaries — [safetensors](/glossary/#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](https://huggingface.co/docs/hub/storage-backends) rather than assuming a number.

## 6. Do it from Python

```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](https://huggingface.co/docs/hub/storage-backends).

Next: [download models with the hf CLI](/guides/hugging-face-cli-download-models/) · [choose a GGUF quantization](/guides/choose-llm-quantization/).