
About
Run workloads on Hugging Face Jobs with managed CPUs, GPUs, TPUs, secrets, and Hub persistence.
source: "https://github.com/huggingface/skills/tree/main/skills/huggingface-jobs" name: hugging-face-jobs description: Run workloads on Hugging Face Jobs with managed CPUs, GPUs, TPUs, secrets, and Hub persistence. license: Complete terms in LICENSE.txt risk: unknown
Running Workloads on Hugging Face Jobs
Overview
Run any workload on fully managed Hugging Face infrastructure. No local setup required—jobs run on cloud CPUs, GPUs, or TPUs and can persist results to the Hugging Face Hub.
Common use cases:
- Data Processing - Transform, filter, or analyze large datasets
- Batch Inference - Run inference on thousands of samples
- Experiments & Benchmarks - Reproducible ML experiments
- Model Training - Fine-tune models (see
model-trainerskill for TRL-specific training) - Synthetic Data Generation - Generate datasets using LLMs
- Development & Testing - Test code without local GPU setup
- Scheduled Jobs - Automate recurring tasks
For model training specifically: See the model-trainer skill for TRL-based training workflows.
When to Use This Skill
Use this skill when users want to:
- Run Python workloads on cloud infrastructure
- Execute jobs without local GPU/TPU setup
- Process data at scale
- Run batch inference or experiments
- Schedule recurring tasks
- Use GPUs/TPUs for any workload
- Persist results to the Hugging Face Hub
Key Directives
When assisting with jobs:
-
ALWAYS use
hf_jobs()MCP tool - Submit jobs usinghf_jobs("uv", {...})orhf_jobs("run", {...}). Thescriptparameter accepts Python code directly. Do NOT save to local files unless the user explicitly requests it. Pass the script content as a string tohf_jobs(). -
Always handle authentication - Jobs that interact with the Hub require
HF_TOKENvia secrets. See Token Usage section below. -
Provide job details after submission - After submitting, provide job ID, monitoring URL, estimated time, and note that the user can request status checks later.
-
Set appropriate timeouts - Default 30min may be insufficient for long-running tasks.
Prerequisites Checklist
Before starting any job, verify:
✅ Account & Authentication
- Hugging Face Account with Pro, Team, or Enterprise plan (Jobs require paid plan)
- Authenticated login: Check with
hf_whoami() - HF_TOKEN for Hub Access ⚠️ CRITICAL - Required for any Hub operations (push models/datasets, download private repos, etc.)
- Token must have appropriate permissions (read for downloads, write for uploads)
✅ Token Usage (See Token Usage section for details)
When tokens are required:
- Pushing models/datasets to Hub
- Accessing private repositories
- Using Hub APIs in scripts
- Any authenticated Hub operations
How to provide tokens:
# hf_jobs MCP tool — $HF_TOKEN is auto-replaced with real token:
{"secrets": {"HF_TOKEN": "$HF_TOKEN"}}
# HfApi().run_uv_job() — MUST pass actual token:
from huggingface_hub import get_token
secrets={"HF_TOKEN": get_token()}
⚠️ CRITICAL: The $HF_TOKEN placeholder is ONLY auto-replaced by the hf_jobs MCP tool. When using HfApi().run_uv_job(), you MUST pass the real token via get_token(). Passing the literal string "$HF_TOKEN" results in a 9-character invalid token and 401 errors.
Token Usage Guide
Understanding Tokens
What are HF Tokens?
- Authentication credentials for Hugging Face Hub
- Required for authenticated operations (push, private repos, API access)
- Stored securely on your machine after
hf auth login
Token Types:
- Read Token - Can download models/datasets, read private repos
- Write Token - Can push models/datasets, create repos, modify content
- Organization Token - Can act on behalf of an organization
When Tokens Are Required
Always Required:
- Pushing models/datasets to Hub
- Accessing private repositories
- Creating new repositories
- Modifying existing repositories
- Using Hub APIs programmatically
Not Required:
- Downloading public models/datasets
- Running jobs that don't interact with Hub
- Reading public repository information
How to Provide Tokens to Jobs
Method 1: Automatic Token (Recommended)
hf_jobs("uv", {
"script": "your_script.py",
"secrets": {"HF_TOKEN": "$HF_TOKEN"} # ✅ Automatic replacement
})
How it works:
$HF_TOKENis a placeholder that gets replaced with your actual token- Uses the token from your logged-in session (
hf auth login) - Most secure and convenient method
- Token is encrypted server-side when passed as a secret
Benefits:
- No token exposure in code
- Uses your current login session
- Automatically updated if you re-login
- Works seamlessly with MCP tools
Method 2: Explicit Token (Not Recommended)
hf_jobs("uv", {
"script": "your_script.py",
"secrets": {"HF_TOKEN": "hf_a