How to Upload and Share a Model on Hugging Face

Sharing a model on the Hugging Face Hub means creating a model repo, uploading weights and configs, and writing a Model Card others can trust. Upload alone does not turn on Inference Providers widgets. Start from /explore/huggingface for the wider Hub map.

This guide walks through prep, card writing, upload, gates, and post publish checks. Dataset provenance pairs with /blog/how-to-explore-and-use-datasets-on-hugging-face. Trying models from other people first is covered in /blog/how-to-browse-and-try-models-on-the-hugging-face-hub.

Treat publishing as a product release, not as a file dump. Readers decide in minutes whether your card answers intended use, limits, and how to load the model. If those answers are missing, downloads stall and support questions pile up in Discussions. A careful first publish saves repeat cleanup commits later.

When to upload to the Hub

Upload when you want versioned weights, public or org private sharing, and a standard place for cards and discussions. Use private repos for early checkpoints. Go public when license, eval notes, and limitations are ready. Choose Inference Endpoints later if you need dedicated always on hosting separate from Providers.

Upload early drafts to a private org repo when multiple trainers need the same checkpoint. Upload a public release when you can defend the card in front of a skeptical reviewer. Those are different moments. Mixing them creates either oversharing of half baked weights or under sharing of models that others could already use safely.

What good sharing requires

A usable share includes files, a Model Card, license metadata, and honest limitations. Gated models need an acceptance flow when you must control who downloads. Hub Free, PRO, Team, and Enterprise seats affect private storage and collaboration. See huggingface.co/pro or huggingface.co/pricing for seat details. Inference credits remain a separate topic.

Good sharing also means naming repos so humans can scan an org page. Include the task in the name when possible. Avoid cute names that hide whether the artifact is a base model, an adapter, or a merged checkpoint. Future tooling and teammates will thank you when the repo id explains itself.

Step by step upload workflow

1. Prepare files and training provenance

Collect config, tokenizer, weights, and a short training note. Record dataset ids and revisions. Incomplete provenance makes cards weak and reviews slow.

Upload prep inventory
[ ] config.json / model config
[ ] tokenizer files
[ ] weights (safetensors preferred when applicable)
[ ] training script link or commit
[ ] dataset ids + revisions
[ ] eval metrics table draft
[ ] license decision

2. Create the model repository

Create a model repo under your user or org on the Hub. Pick visibility. Use a clear name that matches the task. Enable discussions if you want community feedback.

# CLI style create (confirm current huggingface-cli flags in docs)
huggingface-cli repo create my-org/ticket-summarizer --type model
# Then clone or use HfApi upload helpers

3. Write the Model Card before the marketing blurb

Draft the Model Card with intended use, limitations, training data, and eval results. Empty cards slow adoption and increase misuse risk.

---
license: apache-2.0
library_name: transformers
pipeline_tag: text2text-generation
tags:
  - summarization
  - support-tickets
---

# Ticket Summarizer

## Model Details
Base model, parameter count, and training setup.

## Intended Use
Summarize English support tickets into decisions and actions.

## Limitations
May invent owners if the source text is ambiguous. Not for medical advice.

## Training Data
List Hub dataset ids and revisions.

## Evaluation
Metric table on a frozen eval split.

## How to Use
Short code snippet with InferenceClient or transformers.

4. Upload weights with the hub client

Use huggingface hub helpers to upload folders or large files. Verify the commit on the Hub UI. Keep a local checksum log for release managers.

from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ["HF_TOKEN"])
api.upload_folder(
    folder_path="./release_artifacts",
    repo_id="my-org/ticket-summarizer",
    repo_type="model",
    commit_message="Add initial weights and tokenizer",
)

5. Configure license, gates, and org access

Set license metadata to match the card. Add a gate if downloads must be approved. For org private models, confirm Team or Enterprise access patterns in Hugging Face docs.

Access checklist
Visibility: private / public
License metadata matches card: yes/no
Gated access enabled: yes/no
Approver owner:
Internal wiki link for who may accept the gate:
Token guidance: fine grained tokens for automation only

6. Post publish verification

Clone fresh into a clean directory. Load the model. Run the golden eval. Remember: upload does not auto enable Inference Providers widgets. If you need serverless chat later, follow provider requirements separately, and see /blog/how-to-use-hugging-face-inference-providers-for-chat-completion.

Post publish checks
[ ] Fresh clone loads without missing files
[ ] pipeline_tag correct on the Hub page
[ ] Model Card renders
[ ] License visible
[ ] Golden eval metrics match training report
[ ] Providers widget expected? If yes, confirm hosting path separately
[ ] Inference Endpoints needed? Track as a distinct project

Copyable sharing templates

These snippets cover cards, release notes, and communication with teammates.

Minimal transformers load smoke test

from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

repo = "my-org/ticket-summarizer"
tok = AutoTokenizer.from_pretrained(repo)
model = AutoModelForSeq2SeqLM.from_pretrained(repo)
inputs = tok("Summarize: customer wants refund for late order", return_tensors="pt")
out = model.generate(**inputs, max_new_tokens=64)
print(tok.decode(out[0], skip_special_tokens=True))

Release notes blurb

Release notes
Repo: my-org/ticket-summarizer
Revision:
Changes: initial public share
Eval: ROUGE/other on frozen split ...
Known issues: may over shorten action items
Not included: Inference Providers widget (not auto enabled by upload)
Next: consider Endpoints if always on latency required

Card section for ethical considerations

## Ethical Considerations
- Do not use for automated legal decisions
- Review outputs when tickets include vulnerable customers
- Dataset may underrepresent non English speakers
- Report issues via Hub discussions

Org private upload with HfApi

from huggingface_hub import HfApi
import os

api = HfApi(token=os.environ["HF_TOKEN"])
api.upload_file(
    path_or_fileobj="./model.safetensors",
    path_in_repo="model.safetensors",
    repo_id="my-org/ticket-summarizer",
    repo_type="model",
)

Gated model acceptance instructions for users

User access steps
1) Open the model page while logged in
2) Read and accept the gate form
3) Wait for approval if manual review is enabled
4) Create a fine grained token on the same account
5) Retry download or InferenceClient call

Spaces demo handoff note

After model share
Optional Space: Gradio demo pointing at this repo
Do not claim Providers widget works until verified
Link Space from Model Card
See /blog/how-to-run-and-explore-hugging-face-spaces-demos for demo testing

Weak vs strong Model Card

Weak card: "State of the art summarizer. Just works."
Strong card: intended use, limitations, dataset ids, metrics on a frozen split,
license, and a copyable load snippet.
Rule: if you cannot fill limitations, do not publish yet.

Checksum and revision log

Artifact log
File: model.safetensors
SHA256:
Hub revision:
Uploaded by:
Verified load on machine:
Date:

Inference Endpoints reminder

Hosting choices after upload
Providers (serverless multi provider): separate enablement, credits apply
Inference Endpoints (dedicated always on): separate product and bill
Local/transformers: full control, you own GPUs
Pick based on SLA, not on upload convenience

Tips and verification

Prefer safetensors when appropriate. Pin revisions in downstream apps. Keep training data notes aligned with dataset cards. For programmatic calls after share, use /blog/how-to-run-programmatic-inference-with-hugging-face-sdks.

After each public revision, post a short Discussions note or release message that states what changed and what stayed frozen. Consumers who pin revisions need that signal. Silence after a breaking tokenizer change is how integrations fail in the wild while your Hub page still looks fine.

• Write the Model Card before the launch tweet
• Verify a clean clone load after upload
• Set license metadata to match the card text
• Do not assume Providers widgets appear after upload
• Treat Inference Endpoints as a separate always on option

If you plan a Space demo on top of the model, build the Space only after the card and smoke load pass. Demo first, card later usually produces a pretty UI that still cannot answer basic safety questions. Sequence the work so the Hub page remains the source of truth.

Common mistakes

• Publishing weights with an empty Model Card
• Assuming upload enables Inference Providers widgets
• Mismatched license between card YAML and file headers
• Forgetting gated acceptance instructions for consumers
• Mixing Hub seat limits with inference credit expectations
• Skipping a fresh clone smoke test
• Promising always on latency without Inference Endpoints or other dedicated hosting

Related Hugging Face articles: /blog/how-to-explore-and-use-datasets-on-hugging-face, /blog/how-to-use-hugging-face-inference-providers-for-chat-completion, and /blog/how-to-run-and-explore-hugging-face-spaces-demos. Return to /explore/huggingface for the Explore overview.