Share a model or dataset on the Hugging Face Hub

Put a model (its weights and config) or a dataset (its files) at a huggingface.co/... address, and anyone you allow pulls the whole thing into their own code with one line — snapshot_download("you/your-repo"). No ZIP to email, no "which file goes where", every version saved. Make it public for the world, private for named people, or gated so each requester clicks "agree" and you approve them.

Time: ~2 min to your agent to create the repo and push the files; then your real cost is making the card (the README that tells people what it is and how to use it) — call it ~15–30 min of writing you can't delegate well. You'll need: Claude Code, a free Hugging Face account, and a write access token. Last verified: 2026-06-07 · commands checked against huggingface.co/docs (Hub + huggingface_hub). The CLI is hf — the old huggingface-cli was removed in huggingface_hub v1.0. [confirmed]

New to all this? Do Set up Claude Code first (~10 min once), then come back. Sharing plain files people will browse or build on as a project, not load into ML code? A GitHub repo fits better — the Hub shines when the recipient pulls weights or rows straight into a script.

Before you begin

Claude Code running in the folder that holds your model or dataset files — ~10 min once. It installs the library, creates the repo, writes a starter card, and pushes everything.
A free Hugging Face account. Sign up at huggingface.co/join — email + password, ~3 min. This is your namespace: repos live at huggingface.co/your-username/your-repo. [confirmed]
A write access token. At huggingface.co/settings/tokens → New token → pick the Write role (a Read token can't push) → name it → copy it once. ~2 min. [confirmed]
- It looks like hf_ followed by a long string. Treat it like a password — anyone holding it can write to your repos. You can revoke and re-issue it any time from the same page.
Decide the shape now, because it changes a couple of flags:
- Model vs dataset — same mechanics, different --repo-type. Models default; datasets need --repo-type dataset on every command. [confirmed]
- Who gets in — public (anyone), private (named people only), or gated (public listing, but each person requests access and you grant it). Covered in Set who gets in below. [confirmed]

New to handing setup to an agent? Read How to ask your agent — one screen, then come back.

Log your agent in once

Your agent acts as you on the Hub through that token. With Claude Code running, say:

Install the huggingface_hub library and log me in to the Hugging Face Hub
with my access token, then run `hf auth whoami` to confirm it worked.

Under the hood it runs pip install -U huggingface_hub (or uv add huggingface_hub) and hf auth login, which prompts for the token and saves it to your machine. hf auth whoami printing your username means you're set — done once, reused for every push after. [confirmed]

The default: ask your agent to create the repo and push

With your files in the current folder, say:

Create a public Hugging Face model repo called "my-cool-model" under my
account, write a starter model card (README.md) describing what it is and
how to load it, then upload every file in this folder to the repo. Give me
the public URL at the end.

Swap in your repo name, and "dataset" + your dataset's name if that's what you're sharing. Your agent creates the repo (hf repos create your-name/my-cool-model), writes a README.md card, and pushes the files (hf upload your-name/my-cool-model . .). You get back a https://huggingface.co/your-name/my-cool-model link — that link is the share. [confirmed]

Large files (weights, big data shards) need no special handling: the Hub stores them on Xet, its large-file backend, automatically — no Git LFS setup, no git lfs track. Just push; files over ~10 MB are chunked and uploaded efficiently for you. [confirmed]

Write a card so people understand it

The card is a plain README.md at the repo root — it renders as the model or dataset's front page. Without one, a visitor sees a bare file list and can't tell what your model does, how to load it, or what license applies. It's the single highest-value thing you make here, and the one part an agent can't fully write for you: only you know the intent, the limits, and what not to use it for. [confirmed]

Two parts, both in that one file:

The text — what it is, what it's for, its limits and biases, how to load it, what data trained it. Hugging Face publishes a template; ask your agent to fill it from your project, then you edit the judgement calls. [confirmed]
The metadata — a small YAML block fenced by --- at the very top. It drives search, filtering, and the license badge:
```
---
license: mit
tags:
  - text-classification
datasets:
  - stanfordnlp/imdb
base_model: distilbert/distilbert-base-uncased
---
```
license shows the licence on the page; datasets and base_model link back to what you built on; tags make you findable. Ask your agent to fill these from your project. [confirmed]

Easiest edit path: on the repo page, click Edit model card (or Edit dataset card) — it opens the README with a metadata helper that autocompletes the common fields. [confirmed]

Set who gets in (public, private, or gated)

Three rungs, set at create time or flipped later:

Public — anyone with the link views and downloads, no account needed to read. Your agent created it this way above. [confirmed]
Private — only you and people you add (in the repo's Settings → members/collaborators). To create one: add --private to the create command, or tell your agent "make it private." [confirmed]
Gated — the repo is listed publicly, but the files are locked behind a request. Each person clicks Agree and request access, sharing their username and email with you; you either auto-grant or approve by hand. Best for a sensitive model you'll release deliberately — early research weights, a dual-use tool, anything you want a name and a reason attached to before handing over. [confirmed]

To gate it, tell your agent "set this repo to gated with manual approval" — it runs hf repos settings your-name/my-cool-model --gated manual (use auto to grant everyone instantly once they agree). Then you review requests on the repo's Settings → Review access requests page: a pending list to Accept or Reject, and an accepted list you can revoke from at any time. [confirmed]

Gating only locks the files, not the page — the name, card, and metadata stay visible to everyone. If even the existence is sensitive, use private instead. [confirmed]

Want extra fields on the request form (company, country, intended use)? Add them as extra_gated_fields in the card's YAML — the gated-models docs list the field types.

→ For the full picture of access rungs across tools, see Who can see it? and, on handing data to Hugging Face, Can you trust the company?.

How the recipient pulls it

This is where the Hub earns its place: the recipient doesn't download a ZIP and guess. They point one line of Python at your repo id and the files land, cached, ready to load.

Whole repo (the usual case — weights + config, or all dataset files):

from huggingface_hub import snapshot_download
path = snapshot_download("your-name/my-cool-model")          # a model
path = snapshot_download("your-name/my-data", repo_type="dataset")  # a dataset

One file from it:

from huggingface_hub import hf_hub_download
cfg = hf_hub_download("your-name/my-cool-model", "config.json")

Both return a local path; nothing is re-downloaded if it's already cached. ~10 sec to write, the rest is download time. [confirmed]

For a private or gated repo, the recipient must be logged in: they run hf auth login once with their own token (and, for gated, must have been granted access first — a request you accept). A plain public repo needs no login at all. [confirmed]

Recipients using transformers, datasets, or diffusers skip even this — AutoModel.from_pretrained("your-name/my-cool-model") and load_dataset("your-name/my-data") pull from the Hub directly. [confirmed]

You're done when

hf auth whoami shows your username, the repo page at huggingface.co/your-name/... renders your card (not a bare file list), and one recipient has pulled it with snapshot_download — or, for a gated repo, requested access and had you accept. From there, sharing the next version is one sentence: "push the updated files." [confirmed]

If it doesn't work

hf auth login says the token is invalid / 401 → the token was mistyped, revoked, or is Read when you need Write. Re-issue a Write token at settings/tokens and run hf auth login --force to replace the stored one. [confirmed]
Push fails with "403 / you don't have write access" → you're pushing to someone else's namespace, or the token lacks write. Confirm the repo id starts with your username (hf auth whoami), and that the token is Write-scoped. For an org repo, you need a write/admin role in that org. [confirmed]
Large-file upload stalls or errors mid-push → almost always the connection, not the format (the Hub handles big files via Xet automatically, no LFS to configure). For very large folders, tell your agent to use hf upload-large-folder instead of hf upload — it's resumable and retries, so an interrupted push picks up where it left off. [confirmed]
A gated requester is stuck on "pending" → you set manual approval and haven't acted. Go to the repo's Settings → Review access requests, Accept them — or switch to --gated auto so everyone who agrees is granted instantly. Note: you can revoke any granted user later, and a rejected user can't re-request. [confirmed]
The card shows raw --- text or no license badge → the YAML block is malformed: it must be the very first thing in the README, opened and closed by a line of exactly ---, with valid YAML between (two-space indents, no tabs). Paste the README to your agent and ask it to fix the front-matter. [confirmed]
command not found: hf → the library installed but the CLI isn't on PATH, or you're on an old huggingface-cli. Re-run pip install -U huggingface_hub (v1.0+ ships hf), or invoke it with no install via uvx hf .... [confirmed]
Anything else → the huggingface_hub upload guide and the Hub repositories guide cover the failure modes. Hand the exact error to your agent — reading and fixing these is what it's best at.

Prefer to do it by hand?

No agent — just you, in a terminal. The short version:

Install + log in. pip install -U huggingface_hub, then hf auth login and paste your Write token. [confirmed]
Create the repo. hf repos create your-name/my-cool-model (add --repo-type dataset for data, --private to lock it). [confirmed]
Add a card. Create a README.md in your folder with the YAML block above plus a few paragraphs on what it is and how to load it. [confirmed]
Push the files. From inside the folder: hf upload your-name/my-cool-model . . (datasets: append --repo-type dataset). The trailing . . means "everything here, to the repo root." [confirmed]
(Optional) gate it. hf repos settings your-name/my-cool-model --gated manual, then approve requests under Settings → Review access requests on the repo page. [confirmed]

Browser-only, no terminal at all? huggingface.co/new creates a repo, and the Files → Add file → Upload button pushes from your computer — fine for a handful of small files, painful for big weights. [confirmed]

Watch / read

YouTube blocked transcript pulls on 2026-06-07, so these aren't verified line-by-line — judged on title, length, and channel. All three are from Hugging Face's own course channel, so they track the official flow closely; lean on the written guide below if a video drifts.

Uploading a dataset to the Hub — Hugging Face, 2:05. The fastest end-to-end: create a dataset repo and push files. Why this one: shortest official walkthrough — the exact create-and-push arc on this page, for the dataset case.
The Push to Hub API (PyTorch) — Hugging Face, 5:06. Pushing a model and its card from code, plus how it lands on the repo page. Why this one: shows the model side and what the rendered card looks like.
Managing a repo on the Model Hub — Hugging Face, 7:55. The repo's settings, files, and history. Why this one: covers the manage/settings surface where gating and privacy live. Slightly longer — skim to the settings part.

Best written walkthrough: Hugging Face's own Getting Started with Repositories (create a repo, add files, large files via Xet) paired with the huggingface_hub upload guide (upload_file, upload_folder, hf upload). For cards, the Model Cards guide; for request-to-access, the Gated models guide. The authoritative sources these commands were checked against. [confirmed]

People should just see a result or a demo, not load files into code? → a Claude Artifact or a deployed website opens in any browser, no account, nothing to run.
It's a project they'll read and build on as a set of files, not weights or rows? → a GitHub repository hands over the whole thing with every version tracked.
You want a live, clickable demo of the model, not just the weights? → a Hugging Face Space hosts a running app (created the same way, --repo-type space) — a heavier lift than a model repo, so reach for it only when people need to try it, not load it.

Sources

Getting Started with Repositories — create a repo (public/private), add files via CLI/git, large files on Xet (git xet, no LFS setup) — checked 2026-06-07
Upload files to the Hub — upload_file, upload_folder, hf upload, --repo-type dataset, upload_large_folder — checked 2026-06-07
Download files from the Hub — hf_hub_download, snapshot_download, repo_type, hf download — checked 2026-06-07
Command Line Interface (hf) — hf auth login, hf auth whoami, hf repos create, hf repos settings --gated, hf upload, install via pip / uvx hf — checked 2026-06-07
User access tokens — Read vs Write vs fine-grained roles, create at settings/tokens, write needed to push — checked 2026-06-07
Model Cards — card is README.md, YAML metadata (license, tags, datasets, base_model), Edit-card UI, template link — checked 2026-06-07
Gated models — enable access requests, auto vs manual approval, review/accept/reject, extra_gated_fields, requester flow — checked 2026-06-07
Say hello to hf: a faster, friendlier CLI — hf <resource> <action> replaces huggingface-cli — checked 2026-06-07
Migrating to huggingface_hub v1.0 — huggingface-cli removed in v1.0, CLI ships in the core package — checked 2026-06-07

Good to know

The CLI is hf, not huggingface-cli. The old name was removed in huggingface_hub v1.0; the [cli] extra is gone too — the CLI ships with the core package (pip install -U huggingface_hub), or run it install-free with uvx hf .... Old tutorials and answers that say huggingface-cli ... still describe the same actions; just substitute hf. [confirmed]
Large files use Xet, not Git LFS. As of recent huggingface_hub, big files are chunked and deduplicated on Hugging Face's Xet backend automatically — no git lfs install, no git lfs track. The .gitattributes the Hub generates already routes common ML extensions through it. [confirmed]
Gating hides the files, not the page. A gated repo's name, card, and metadata stay public; only downloads are locked behind your approval. For something whose very existence is sensitive, use a private repo instead. [confirmed]
Tokens are per-purpose and revocable. Best practice is one token per machine or app, Write only where you push, Read elsewhere — so a leak from a laptop doesn't expose everything. Revoke and re-issue any time at settings/tokens. Org plans (Team/Enterprise) can require fine-grained tokens and admin approval. [confirmed]
Storage is generous but not infinite. Public repos are free; very large private storage and some Enterprise features are paid. Re-check live limits at huggingface.co/pricing. [unclear] (exact free-storage caps not pinned to a single doc — checked 2026-06-07)