Run Python Workloads on Hugging Face Jobs

Runs any workload on fully managed Hugging Face infrastructure - cloud CPUs, GPUs, or TPUs - with no local setup, persisting results to the Hugging Face Hub. Common uses: data processing, batch inference, reproducible experiments, synthetic data generation, development/testing without local GPU access, and scheduled recurring jobs. Model training specifically is covered by the companion model-trainer skill for TRL-based workflows.

Use when a task needs Python workloads run on cloud infrastructure without local GPU/TPU setup, data processing at scale, batch inference or experiments, scheduled recurring tasks, or persisting results to the Hub. Requires a Hugging Face account on a paid Pro/Team/Enterprise plan (Jobs require a paid plan) and an HF_TOKEN for any Hub-interacting job.

Always submit via the hf_jobs() MCP tool - hf_jobs("uv", {...}) for UV scripts or hf_jobs("run", {...}) for Docker-based jobs - passing script content as an inline string rather than saving to a local file:

hf_jobs("uv", {
    "script": """
# /// script
# dependencies = ["transformers", "torch"]
# ///
from transformers import pipeline
classifier = pipeline("sentiment-analysis")
print(classifier("I love Hugging Face!"))
""",
    "flavor": "cpu-basic",
    "timeout": "30m"
})

UV scripts (PEP 723 inline dependencies) are the recommended default; Docker-based jobs (hf_jobs("run", {...})) support custom images, non-Python workloads, and HF Spaces used as images. Local file paths only work with the hf jobs uv run CLI, not the MCP tool - for the MCP tool, read the file's contents into a string or pass a URL.

Token handling is critical: pass secrets={"HF_TOKEN": "$HF_TOKEN"} with the MCP tool (auto-replaced with the real token) versus secrets={"HF_TOKEN": get_token()} with HfApi().run_uv_job() (the literal string "$HF_TOKEN" there produces an invalid 9-character token and 401 errors). Use secrets, never env, since env values appear in job logs while secrets are encrypted server-side.

Hardware flavors span cpu-basic/cpu-upgrade through t4-small/t4-medium, l4x1/l4x4, a10g-small/a10g-large (plus x2/x4 multi-GPU variants), a100-large, and TPU v5e-1x1/v5e-2x2/v5e-2x4 - matched to workload size from lightweight data tasks up to 13B+ model inference.

The Jobs environment is ephemeral - all files are deleted when the job ends, so results must be pushed to the Hub, external storage (S3/GCS), or an API before the job exits. Default timeout is 30 minutes; long-running tasks need explicit "timeout" values like "2h" with a 20-30% buffer. Scheduled jobs support @hourly/@daily/@weekly/@monthly or raw CRON expressions via hf_jobs("scheduled uv", {...}). Webhooks can trigger a job automatically on repo/discussion events, with the triggering payload available as the WEBHOOK_PAYLOAD env var.

Job monitoring uses hf_jobs("ps"/"inspect"/"logs"/"cancel", {...}) - jobs are asynchronous, so avoid polling and let the user request status checks.

Built on huggingface_hub's Jobs API (run_uv_job, run_job, create_scheduled_job, create_webhook) and ships ready-to-run scripts (scripts/generate-responses.py for vLLM batch generation, scripts/cot-self-instruct.py for synthetic data, scripts/finepdfs-stats.py for streaming Polars stats) plus reference guides for tokens, hardware, Hub persistence, and troubleshooting.

ML engineers and data teams who need cloud compute for batch inference, data processing, experiments, or scheduled jobs without managing local GPU/TPU infrastructure, using Hugging Face's managed Jobs platform via the hf_jobs() MCP tool, CLI, or Python API.