TL;DR
- Create a free account and generate an access token at huggingface.co
- Install the
huggingface_hubSDK and CLI:pip install --upgrade huggingface_hub - Download models with
snapshot_download()or use the free Inference API - Deploy demos in minutes with Spaces (Gradio/Streamlit)
- Upload your own models with
push_to_hub()or the CLI
1. Create an Account and Token
Hugging Face Hub uses access tokens for authentication. Here’s how to set one up:
Step 1: Sign Up
- Go to huggingface.co/join
- Enter your email, username, and password
- Verify your email (check your inbox)
Step 2: Generate an Access Token
- Navigate to huggingface.co/settings/tokens
- Click "New token"
- Set a name (e.g.,
my-laptop-cli) and role (select "Write" for full access) - Click "Generate token"
- Copy the token immediately (it won’t be shown again)
Expected output:
hf_abcdefghijklmnopqrstuvwxyz1234567890
Step 3: Save Your Token Securely
# Save to a file (Linux/macOS)
echo "hf_abcdefghijklmnopqrstuvwxyz1234567890" > ~/.huggingface/token
# Set permissions (Linux/macOS)
chmod 600 ~/.huggingface/token
Gotcha: Never commit your token to Git. Add ~/.huggingface/token to your .gitignore.
2. Set Up huggingface-cli
The CLI is the fastest way to interact with the Hub from your terminal.
Install the CLI
pip install --upgrade "huggingface_hub[cli]"
Log In
huggingface-cli login
Expected output:
_| _| _| _| _|_|_| _|_|_| _|_|_| _| _|
_| _| _| _| _| _| _| _|_| _|
_|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _|
_| _| _| _| _| _| _| _| _| _| _|_
_| _| _|_| _|_|_| _|_|_| _|_|_| _| _|
To login, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens.
Token:
Paste your token and press Enter.
Common error:
ValueError: Token is invalid. Please try again.
Fix: Regenerate your token and ensure you copied it correctly.
3. Download and Use Models
Hugging Face Hub hosts over 500,000 models (as of 2026) Hugging Face Hub Stats. Here’s how to use them:
Option 1: Download with snapshot_download
from huggingface_hub import snapshot_download
# Download a model (e.g., "bert-base-uncased")
model_path = snapshot_download(
repo_id="bert-base-uncased",
local_dir="./bert-base-uncased",
local_dir_use_symlinks=False # Avoid symlinks for portability
)
print(f"Model downloaded to: {model_path}")
Expected output:
Model downloaded to: ./bert-base-uncased
Option 2: Use with Transformers
from transformers import AutoTokenizer, AutoModel
tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModel.from_pretrained("bert-base-uncased")
inputs = tokenizer("Hello, world!", return_tensors="pt")
outputs = model(**inputs)
print(outputs.last_hidden_state.shape)
Expected output:
torch.Size([1, 4, 768])
Gotcha: Large models (e.g., meta-llama/Llama-3-70b) may require 100GB+ disk space. Use ignore_patterns=["*.bin"] in snapshot_download to skip weights.
4. Inference API (Free Tier)
The Inference API lets you run models without downloading them. Free tier includes 1,000 requests/day Inference API Docs.
Example: Text Generation
import requests
API_URL = "https://api-inference.huggingface.co/models/mistralai/Mistral-7B-v0.1"
headers = {"Authorization": "Bearer hf_abcdefghijklmnopqrstuvwxyz1234567890"}
def query(payload):
response = requests.post(API_URL, headers=headers, json=payload)
return response.json()
output = query({
"inputs": "Explain AI to a 5-year-old:",
"parameters": {"max_new_tokens": 50}
})
print(output[0]["generated_text"])
Expected output:
AI is like a super-smart robot friend that learns from books and games to help us with fun stuff, like drawing or telling stories!
Rate Limits
| Plan | Requests/Day | Requests/Second |
|---|---|---|
| Free | 1,000 | 1 |
| Pro | 10,000 | 5 |
| Enterprise | Custom | Custom |
Gotcha: Free tier requests may queue during peak times. Upgrade to Pro for priority access.
5. Spaces for Demos
Spaces are interactive web apps (Gradio/Streamlit) hosted on Hugging Face. Perfect for demos or internal tools.
Step 1: Create a Space
- Go to huggingface.co/spaces
- Click "Create new Space"
- Select:
- Name:
my-first-demo - License:
MIT - Hardware:
CPU(free) orA10G(paid, $0.50/hour) - SDK:
Gradio(easiest for beginners)
- Name:
- Click "Create Space"
Step 2: Add a Simple App
Replace the contents of app.py with:
import gradio as gr
def greet(name):
return f"Hello {name}!"
demo = gr.Interface(fn=greet, inputs="text", outputs="text")
demo.launch()
Step 3: Deploy
- Click "Commit" to push changes
- Wait 30-60 seconds for the app to build
- Share your Space URL (e.g.,
https://hf.co/spaces/your-username/my-first-demo)
Gotcha: Free Spaces idle after 30 minutes. Use the "Always On" feature (paid) to prevent this.
6. Upload Your Own Models
Share your models with the world (or keep them private).
Option 1: Using the CLI
# Create a new repository
huggingface-cli repo create my-awesome-model --type model
# Clone the repo
git lfs install
git clone https://huggingface.co/your-username/my-awesome-model
cd my-awesome-model
# Add your model files (e.g., PyTorch weights)
cp /path/to/your/model/* .
# Commit and push
git add .
git commit -m "Add my awesome model"
git push
Option 2: Using the Python SDK
from huggingface_hub import HfApi
api = HfApi()
api.upload_file(
path_or_fileobj="/path/to/pytorch_model.bin",
path_in_repo="pytorch_model.bin",
repo_id="your-username/my-awesome-model",
repo_type="model",
)
Gotcha: Large files (>5GB) may time out. Use huggingface_hub with chunked uploads:
from huggingface_hub import upload_file
upload_file(
path_or_fileobj="/path/to/large-model.bin",
path_in_repo="large-model.bin",
repo_id="your-username/my-awesome-model",
repo_type="model",
chunk_size=10 * 1024 * 1024, # 10MB chunks
)
7. Transformers Library Quickstart
The transformers library is the easiest way to use Hugging Face models.
Install Transformers
pip install --upgrade transformers
Example: Text Classification
from transformers import pipeline
classifier = pipeline("text-classification", model="distilbert-base-uncased-finetuned-sst-2-english")
result = classifier("I love Hugging Face Hub!")
print(result)
Expected output:
[{'label': 'POSITIVE', 'score': 0.9998}]
Example: Image Classification
from transformers import pipeline
classifier = pipeline("image-classification", model="google/vit-base-patch16-224")
result = classifier("https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/cat.png")
print(result)
Expected output:
[{'label': 'tabby cat', 'score': 0.98}]
Gotcha: Some models require specific dependencies (e.g., torch for PyTorch models). Install them with:
pip install torch tensorflow # For PyTorch/TensorFlow models
What's Next?
- Explore models: Browse huggingface.co/models and try 3 models in the Inference API.
- Deploy a Space: Build a Gradio app for your favorite model (e.g., a chatbot or image generator).
- Contribute: Upload a fine-tuned model or dataset to share with the community.
For teams scaling AI workflows, Hyperion Consulting offers end-to-end tools and consulting to streamline your Hugging Face deployments.
