Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions docs/hub/jobs-overview.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,16 @@
# Jobs Overview

Run compute jobs on Hugging Face infrastructure with a familiar UV & Docker-like interface!
Hugging Face Jobs runs your code on remote CPUs and GPUs. Use it to fine-tune models, run inference over datasets, or process data.

A Job runs a command in an environment on the hardware you choose. You can follow its status and logs from the terminal or on the Hub.

[Start with the Quickstart](./jobs-quickstart) to run your first CPU and GPU Jobs, or [browse examples](./jobs-examples) for a workload to adapt.

<div class="flex justify-center">
<img src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/jobs/hf_jobs_run_and_uv_run.gif"/>
</div>

<div class="-mt-3 grid grid-cols-2 rounded-xl border lg:grid-cols-4"><div class="border-r p-4 max-lg:border-b"><h3 class="flex items-center gap-1.5 font-semibold"><svg class="text-green-500 flex-none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 13 13"><path d="M5.22433 7.95134L3.91933 6.64634C3.80933 6.53634 3.67433 6.48134 3.51433 6.48134C3.35433 6.48134 3.21433 6.54134 3.09433 6.66134C2.98433 6.77134 2.92933 6.91134 2.92933 7.08134C2.92933 7.25134 2.98433 7.39134 3.09433 7.50134L4.80433 9.21134C4.91433 9.32134 5.05433 9.37634 5.22433 9.37634C5.39433 9.37634 5.53433 9.32134 5.64433 9.21134L9.04933 5.80634C9.15933 5.69634 9.21433 5.56134 9.21433 5.40134C9.21433 5.24134 9.15433 5.10134 9.03433 4.98134C8.92433 4.87134 8.78433 4.81634 8.61433 4.81634C8.44433 4.81634 8.30433 4.87134 8.19433 4.98134L5.22433 7.95134ZM6.06433 12.8713C5.23433 12.8713 4.45433 12.7137 3.72433 12.3985C2.99433 12.0837 2.35933 11.6563 1.81933 11.1163C1.27933 10.5763 0.851931 9.94134 0.537131 9.21134C0.221931 8.48134 0.0643311 7.70134 0.0643311 6.87134C0.0643311 6.04134 0.221931 5.26134 0.537131 4.53134C0.851931 3.80134 1.27933 3.16634 1.81933 2.62634C2.35933 2.08634 2.99433 1.65874 3.72433 1.34354C4.45433 1.02874 5.23433 0.871338 6.06433 0.871338C6.89433 0.871338 7.67433 1.02874 8.40433 1.34354C9.13433 1.65874 9.76933 2.08634 10.3093 2.62634C10.8493 3.16634 11.2767 3.80134 11.5915 4.53134C11.9067 5.26134 12.0643 6.04134 12.0643 6.87134C12.0643 7.70134 11.9067 8.48134 11.5915 9.21134C11.2767 9.94134 10.8493 10.5763 10.3093 11.1163C9.76933 11.6563 9.13433 12.0837 8.40433 12.3985C7.67433 12.7137 6.89433 12.8713 6.06433 12.8713Z" fill="currentColor"></path></svg>UV & Docker-like CLI</h3> <p class="font-mono text-xs text-gray-600">uv,run,ps,logs,stats,inspect</p></div> <div class="p-4 dark:border-gray-900 max-lg:border-b lg:border-r"><h3 class="flex items-center gap-1.5 font-semibold"><svg class="text-green-500 flex-none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 13 13"><path d="M5.22433 7.95134L3.91933 6.64634C3.80933 6.53634 3.67433 6.48134 3.51433 6.48134C3.35433 6.48134 3.21433 6.54134 3.09433 6.66134C2.98433 6.77134 2.92933 6.91134 2.92933 7.08134C2.92933 7.25134 2.98433 7.39134 3.09433 7.50134L4.80433 9.21134C4.91433 9.32134 5.05433 9.37634 5.22433 9.37634C5.39433 9.37634 5.53433 9.32134 5.64433 9.21134L9.04933 5.80634C9.15933 5.69634 9.21433 5.56134 9.21433 5.40134C9.21433 5.24134 9.15433 5.10134 9.03433 4.98134C8.92433 4.87134 8.78433 4.81634 8.61433 4.81634C8.44433 4.81634 8.30433 4.87134 8.19433 4.98134L5.22433 7.95134ZM6.06433 12.8713C5.23433 12.8713 4.45433 12.7137 3.72433 12.3985C2.99433 12.0837 2.35933 11.6563 1.81933 11.1163C1.27933 10.5763 0.851931 9.94134 0.537131 9.21134C0.221931 8.48134 0.0643311 7.70134 0.0643311 6.87134C0.0643311 6.04134 0.221931 5.26134 0.537131 4.53134C0.851931 3.80134 1.27933 3.16634 1.81933 2.62634C2.35933 2.08634 2.99433 1.65874 3.72433 1.34354C4.45433 1.02874 5.23433 0.871338 6.06433 0.871338C6.89433 0.871338 7.67433 1.02874 8.40433 1.34354C9.13433 1.65874 9.76933 2.08634 10.3093 2.62634C10.8493 3.16634 11.2767 3.80134 11.5915 4.53134C11.9067 5.26134 12.0643 6.04134 12.0643 6.87134C12.0643 7.70134 11.9067 8.48134 11.5915 9.21134C11.2767 9.94134 10.8493 10.5763 10.3093 11.1163C9.76933 11.6563 9.13433 12.0837 8.40433 12.3985C7.67433 12.7137 6.89433 12.8713 6.06433 12.8713Z" fill="currentColor"></path></svg>Any Hardware</h3> <p class="text-sm text-gray-600">CPUs to A100s &amp; TPUs</p></div> <div class="border-r p-4"><h3 class="flex items-center gap-1.5 font-semibold"><svg class="text-green-500 flex-none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 13 13"><path d="M5.22433 7.95134L3.91933 6.64634C3.80933 6.53634 3.67433 6.48134 3.51433 6.48134C3.35433 6.48134 3.21433 6.54134 3.09433 6.66134C2.98433 6.77134 2.92933 6.91134 2.92933 7.08134C2.92933 7.25134 2.98433 7.39134 3.09433 7.50134L4.80433 9.21134C4.91433 9.32134 5.05433 9.37634 5.22433 9.37634C5.39433 9.37634 5.53433 9.32134 5.64433 9.21134L9.04933 5.80634C9.15933 5.69634 9.21433 5.56134 9.21433 5.40134C9.21433 5.24134 9.15433 5.10134 9.03433 4.98134C8.92433 4.87134 8.78433 4.81634 8.61433 4.81634C8.44433 4.81634 8.30433 4.87134 8.19433 4.98134L5.22433 7.95134ZM6.06433 12.8713C5.23433 12.8713 4.45433 12.7137 3.72433 12.3985C2.99433 12.0837 2.35933 11.6563 1.81933 11.1163C1.27933 10.5763 0.851931 9.94134 0.537131 9.21134C0.221931 8.48134 0.0643311 7.70134 0.0643311 6.87134C0.0643311 6.04134 0.221931 5.26134 0.537131 4.53134C0.851931 3.80134 1.27933 3.16634 1.81933 2.62634C2.35933 2.08634 2.99433 1.65874 3.72433 1.34354C4.45433 1.02874 5.23433 0.871338 6.06433 0.871338C6.89433 0.871338 7.67433 1.02874 8.40433 1.34354C9.13433 1.65874 9.76933 2.08634 10.3093 2.62634C10.8493 3.16634 11.2767 3.80134 11.5915 4.53134C11.9067 5.26134 12.0643 6.04134 12.0643 6.87134C12.0643 7.70134 11.9067 8.48134 11.5915 9.21134C11.2767 9.94134 10.8493 10.5763 10.3093 11.1163C9.76933 11.6563 9.13433 12.0837 8.40433 12.3985C7.67433 12.7137 6.89433 12.8713 6.06433 12.8713Z" fill="currentColor"></path></svg>Run Anything</h3> <p class="text-sm text-gray-600">UV, Docker, HF Spaces &amp; more</p></div> <div class="p-4"><h3 class="flex items-center gap-1.5 font-semibold"><svg class="text-green-500 flex-none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 13 13"><path d="M5.22433 7.95134L3.91933 6.64634C3.80933 6.53634 3.67433 6.48134 3.51433 6.48134C3.35433 6.48134 3.21433 6.54134 3.09433 6.66134C2.98433 6.77134 2.92933 6.91134 2.92933 7.08134C2.92933 7.25134 2.98433 7.39134 3.09433 7.50134L4.80433 9.21134C4.91433 9.32134 5.05433 9.37634 5.22433 9.37634C5.39433 9.37634 5.53433 9.32134 5.64433 9.21134L9.04933 5.80634C9.15933 5.69634 9.21433 5.56134 9.21433 5.40134C9.21433 5.24134 9.15433 5.10134 9.03433 4.98134C8.92433 4.87134 8.78433 4.81634 8.61433 4.81634C8.44433 4.81634 8.30433 4.87134 8.19433 4.98134L5.22433 7.95134ZM6.06433 12.8713C5.23433 12.8713 4.45433 12.7137 3.72433 12.3985C2.99433 12.0837 2.35933 11.6563 1.81933 11.1163C1.27933 10.5763 0.851931 9.94134 0.537131 9.21134C0.221931 8.48134 0.0643311 7.70134 0.0643311 6.87134C0.0643311 6.04134 0.221931 5.26134 0.537131 4.53134C0.851931 3.80134 1.27933 3.16634 1.81933 2.62634C2.35933 2.08634 2.99433 1.65874 3.72433 1.34354C4.45433 1.02874 5.23433 0.871338 6.06433 0.871338C6.89433 0.871338 7.67433 1.02874 8.40433 1.34354C9.13433 1.65874 9.76933 2.08634 10.3093 2.62634C10.8493 3.16634 11.2767 3.80134 11.5915 4.53134C11.9067 5.26134 12.0643 6.04134 12.0643 6.87134C12.0643 7.70134 11.9067 8.48134 11.5915 9.21134C11.2767 9.94134 10.8493 10.5763 10.3093 11.1163C9.76933 11.6563 9.13433 12.0837 8.40433 12.3985C7.67433 12.7137 6.89433 12.8713 6.06433 12.8713Z" fill="currentColor"></path></svg>Pay-as-you-go</h3> <p class="text-sm text-gray-600">Pay only for seconds used</p></div></div>

The Hugging Face Hub provides compute for AI and data workflows via Jobs.

Jobs runs on Hugging Face infrastructure and aim at providing AI builders, Data engineers, developers and AI agents an easy access to cloud infrastructure to run their workloads. They are ideal to fine tune AI models and run inference with GPUs, but also for data ingestion and processing as well.

A job is defined with a command to run (e.g. a UV or python command), a hardware flavor (CPU, GPU, TPU), and optionally a Docker image from Hugging Face Spaces or Docker Hub. Many jobs can run in parallel, which is useful e.g. for parameter tuning or parallel inference and data processing.
<div class="-mt-3 grid grid-cols-2 rounded-xl border lg:grid-cols-4"><div class="border-r p-4 max-lg:border-b"><h3 class="flex items-center gap-1.5 font-semibold"><svg class="text-green-500 flex-none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 13 13"><path d="M5.22433 7.95134L3.91933 6.64634C3.80933 6.53634 3.67433 6.48134 3.51433 6.48134C3.35433 6.48134 3.21433 6.54134 3.09433 6.66134C2.98433 6.77134 2.92933 6.91134 2.92933 7.08134C2.92933 7.25134 2.98433 7.39134 3.09433 7.50134L4.80433 9.21134C4.91433 9.32134 5.05433 9.37634 5.22433 9.37634C5.39433 9.37634 5.53433 9.32134 5.64433 9.21134L9.04933 5.80634C9.15933 5.69634 9.21433 5.56134 9.21433 5.40134C9.21433 5.24134 9.15433 5.10134 9.03433 4.98134C8.92433 4.87134 8.78433 4.81634 8.61433 4.81634C8.44433 4.81634 8.30433 4.87134 8.19433 4.98134L5.22433 7.95134ZM6.06433 12.8713C5.23433 12.8713 4.45433 12.7137 3.72433 12.3985C2.99433 12.0837 2.35933 11.6563 1.81933 11.1163C1.27933 10.5763 0.851931 9.94134 0.537131 9.21134C0.221931 8.48134 0.0643311 7.70134 0.0643311 6.87134C0.0643311 6.04134 0.221931 5.26134 0.537131 4.53134C0.851931 3.80134 1.27933 3.16634 1.81933 2.62634C2.35933 2.08634 2.99433 1.65874 3.72433 1.34354C4.45433 1.02874 5.23433 0.871338 6.06433 0.871338C6.89433 0.871338 7.67433 1.02874 8.40433 1.34354C9.13433 1.65874 9.76933 2.08634 10.3093 2.62634C10.8493 3.16634 11.2767 3.80134 11.5915 4.53134C11.9067 5.26134 12.0643 6.04134 12.0643 6.87134C12.0643 7.70134 11.9067 8.48134 11.5915 9.21134C11.2767 9.94134 10.8493 10.5763 10.3093 11.1163C9.76933 11.6563 9.13433 12.0837 8.40433 12.3985C7.67433 12.7137 6.89433 12.8713 6.06433 12.8713Z" fill="currentColor"></path></svg>UV & Docker-like CLI</h3> <p class="font-mono text-xs text-gray-600">uv,run,ps,logs,stats,inspect</p></div> <div class="p-4 dark:border-gray-900 max-lg:border-b lg:border-r"><h3 class="flex items-center gap-1.5 font-semibold"><svg class="text-green-500 flex-none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 13 13"><path d="M5.22433 7.95134L3.91933 6.64634C3.80933 6.53634 3.67433 6.48134 3.51433 6.48134C3.35433 6.48134 3.21433 6.54134 3.09433 6.66134C2.98433 6.77134 2.92933 6.91134 2.92933 7.08134C2.92933 7.25134 2.98433 7.39134 3.09433 7.50134L4.80433 9.21134C4.91433 9.32134 5.05433 9.37634 5.22433 9.37634C5.39433 9.37634 5.53433 9.32134 5.64433 9.21134L9.04933 5.80634C9.15933 5.69634 9.21433 5.56134 9.21433 5.40134C9.21433 5.24134 9.15433 5.10134 9.03433 4.98134C8.92433 4.87134 8.78433 4.81634 8.61433 4.81634C8.44433 4.81634 8.30433 4.87134 8.19433 4.98134L5.22433 7.95134ZM6.06433 12.8713C5.23433 12.8713 4.45433 12.7137 3.72433 12.3985C2.99433 12.0837 2.35933 11.6563 1.81933 11.1163C1.27933 10.5763 0.851931 9.94134 0.537131 9.21134C0.221931 8.48134 0.0643311 7.70134 0.0643311 6.87134C0.0643311 6.04134 0.221931 5.26134 0.537131 4.53134C0.851931 3.80134 1.27933 3.16634 1.81933 2.62634C2.35933 2.08634 2.99433 1.65874 3.72433 1.34354C4.45433 1.02874 5.23433 0.871338 6.06433 0.871338C6.89433 0.871338 7.67433 1.02874 8.40433 1.34354C9.13433 1.65874 9.76933 2.08634 10.3093 2.62634C10.8493 3.16634 11.2767 3.80134 11.5915 4.53134C11.9067 5.26134 12.0643 6.04134 12.0643 6.87134C12.0643 7.70134 11.9067 8.48134 11.5915 9.21134C11.2767 9.94134 10.8493 10.5763 10.3093 11.1163C9.76933 11.6563 9.13433 12.0837 8.40433 12.3985C7.67433 12.7137 6.89433 12.8713 6.06433 12.8713Z" fill="currentColor"></path></svg>CPUs &amp; GPUs</h3> <p class="text-sm text-gray-600">Choose hardware for your workload</p></div> <div class="border-r p-4"><h3 class="flex items-center gap-1.5 font-semibold"><svg class="text-green-500 flex-none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 13 13"><path d="M5.22433 7.95134L3.91933 6.64634C3.80933 6.53634 3.67433 6.48134 3.51433 6.48134C3.35433 6.48134 3.21433 6.54134 3.09433 6.66134C2.98433 6.77134 2.92933 6.91134 2.92933 7.08134C2.92933 7.25134 2.98433 7.39134 3.09433 7.50134L4.80433 9.21134C4.91433 9.32134 5.05433 9.37634 5.22433 9.37634C5.39433 9.37634 5.53433 9.32134 5.64433 9.21134L9.04933 5.80634C9.15933 5.69634 9.21433 5.56134 9.21433 5.40134C9.21433 5.24134 9.15433 5.10134 9.03433 4.98134C8.92433 4.87134 8.78433 4.81634 8.61433 4.81634C8.44433 4.81634 8.30433 4.87134 8.19433 4.98134L5.22433 7.95134ZM6.06433 12.8713C5.23433 12.8713 4.45433 12.7137 3.72433 12.3985C2.99433 12.0837 2.35933 11.6563 1.81933 11.1163C1.27933 10.5763 0.851931 9.94134 0.537131 9.21134C0.221931 8.48134 0.0643311 7.70134 0.0643311 6.87134C0.0643311 6.04134 0.221931 5.26134 0.537131 4.53134C0.851931 3.80134 1.27933 3.16634 1.81933 2.62634C2.35933 2.08634 2.99433 1.65874 3.72433 1.34354C4.45433 1.02874 5.23433 0.871338 6.06433 0.871338C6.89433 0.871338 7.67433 1.02874 8.40433 1.34354C9.13433 1.65874 9.76933 2.08634 10.3093 2.62634C10.8493 3.16634 11.2767 3.80134 11.5915 4.53134C11.9067 5.26134 12.0643 6.04134 12.0643 6.87134C12.0643 7.70134 11.9067 8.48134 11.5915 9.21134C11.2767 9.94134 10.8493 10.5763 10.3093 11.1163C9.76933 11.6563 9.13433 12.0837 8.40433 12.3985C7.67433 12.7137 6.89433 12.8713 6.06433 12.8713Z" fill="currentColor"></path></svg>Run your code</h3> <p class="text-sm text-gray-600">Python scripts &amp; Docker images</p></div> <div class="p-4"><h3 class="flex items-center gap-1.5 font-semibold"><svg class="text-green-500 flex-none" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" focusable="false" role="img" width="1em" height="1em" preserveAspectRatio="xMidYMid meet" viewBox="0 0 13 13"><path d="M5.22433 7.95134L3.91933 6.64634C3.80933 6.53634 3.67433 6.48134 3.51433 6.48134C3.35433 6.48134 3.21433 6.54134 3.09433 6.66134C2.98433 6.77134 2.92933 6.91134 2.92933 7.08134C2.92933 7.25134 2.98433 7.39134 3.09433 7.50134L4.80433 9.21134C4.91433 9.32134 5.05433 9.37634 5.22433 9.37634C5.39433 9.37634 5.53433 9.32134 5.64433 9.21134L9.04933 5.80634C9.15933 5.69634 9.21433 5.56134 9.21433 5.40134C9.21433 5.24134 9.15433 5.10134 9.03433 4.98134C8.92433 4.87134 8.78433 4.81634 8.61433 4.81634C8.44433 4.81634 8.30433 4.87134 8.19433 4.98134L5.22433 7.95134ZM6.06433 12.8713C5.23433 12.8713 4.45433 12.7137 3.72433 12.3985C2.99433 12.0837 2.35933 11.6563 1.81933 11.1163C1.27933 10.5763 0.851931 9.94134 0.537131 9.21134C0.221931 8.48134 0.0643311 7.70134 0.0643311 6.87134C0.0643311 6.04134 0.221931 5.26134 0.537131 4.53134C0.851931 3.80134 1.27933 3.16634 1.81933 2.62634C2.35933 2.08634 2.99433 1.65874 3.72433 1.34354C4.45433 1.02874 5.23433 0.871338 6.06433 0.871338C6.89433 0.871338 7.67433 1.02874 8.40433 1.34354C9.13433 1.65874 9.76933 2.08634 10.3093 2.62634C10.8493 3.16634 11.2767 3.80134 11.5915 4.53134C11.9067 5.26134 12.0643 6.04134 12.0643 6.87134C12.0643 7.70134 11.9067 8.48134 11.5915 9.21134C11.2767 9.94134 10.8493 10.5763 10.3093 11.1163C9.76933 11.6563 9.13433 12.0837 8.40433 12.3985C7.67433 12.7137 6.89433 12.8713 6.06433 12.8713Z" fill="currentColor"></path></svg>Pay-as-you-go</h3> <p class="text-sm text-gray-600">Pay for the compute you use</p></div></div>

## Run Jobs from anywhere

Expand All @@ -24,20 +22,26 @@ There are multiple tools you can use to run jobs:

## Run any workload

The `hf` Jobs CLI and the `huggingface_hub` Python client offer a UV-like interface to run Python workloads. UV installs the required Python dependencies and run the Python script in one single command. Python dependencies may also be defined in a self-contained UV script, and in this case there is no need to specify anything but the UV script to run the Job.
### Python scripts

Use `hf jobs uv run` to run a Python script remotely. Specify its dependencies with `--with` or in a [script header](https://docs.astral.sh/uv/guides/scripts/#declaring-script-dependencies). Jobs uses uv to install those dependencies before running your code.

```diff
- uv run <script.py>
+ hf jobs uv run <script.py>
```

More generally, Hugging Face Jobs supports any workload based on Docker and a command. Jobs offers a Docker-like interface to rub Jobs, where you can specify a Docker image from Hugging Face Spaces or Docker Hub, as well as the command to run. Docker provides the ability to package ready-to-use environments as Docker images that are shared by the community or custom made. Therefore you may choose or define your Docker image based on what your workloads need (e.g. python, torch, vllm) and run any command. This is more advanced than using UV but provides more flexibility.
### Docker images

Use `hf jobs run` with a Docker image and the command to run. The image provides the tools and libraries your workload needs, whether you're using Python or another language. Choose an [existing image](./jobs-popular-images), use one built from a [Docker Space](./spaces-sdks-docker), or build your own.

```diff
- docker run <image> <command>
+ hf jobs run <image> <command>
```

Many Jobs can run in parallel, for tasks such as parameter tuning, inference and data processing.

## Automate Jobs

Trigger Jobs automatically with a schedule or using webhooks.
Expand Down
Loading
Loading