# Estimating Cost and Runtime of Hugging Face Training Jobs Before Submission

> Estimate Hugging Face training job costs and runtime before submission. Learn how the estimate_cost.py script predicts expenses and duration using model size, hardware pricing, and empirical formulas.

- Repository: [Hugging Face/skills](https://github.com/huggingface/skills)
- Tags: performance
- Published: 2026-03-08

---

**The [`estimate_cost.py`](https://github.com/huggingface/skills/blob/main/estimate_cost.py) script in the `hugging-face-model-trainer` skill calculates training expenses and duration by combining model size detection, hardware pricing tables, and empirical time formulas before you submit the job.**

Estimating cost and runtime of training jobs before submission prevents budget overruns and timeout failures in distributed ML workflows. The `huggingface/skills` repository provides a dedicated cost estimation tool within the `hugging-face-model-trainer` skill that analyzes your model, dataset, and hardware choices to project expenses and recommend safe timeout buffers.

## How the Cost Estimation Script Works

The core logic resides in [`skills/hugging-face-model-trainer/scripts/estimate_cost.py`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/estimate_cost.py). The script implements a deterministic pipeline that translates training configuration into concrete dollar amounts and time estimates.

### Input Parameters and Hardware Configuration

The script uses `argparse` to collect training specifications ([lines 66-73](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/estimate_cost.py#L66-L73)):

- Model identifier (e.g., `Qwen/Qwen2.5-0.5B`)
- Dataset name and optional size
- Hardware flavor (e.g., `a10g-large`, `a100-large`)
- Number of training epochs

Hardware pricing is defined in the static dictionary `HARDWARE_COSTS` ([lines 18-28](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/estimate_cost.py#L18-L28)), which maps each GPU flavor to its hourly USD rate.

### Model Size Detection

To calculate computational load, the script must determine model parameters. The `MODEL_SIZES` map ([lines 30-37](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/estimate_cost.py#L30-L37)) translates common size strings like `0.5B` or `7B` into billions of parameters.

The helper function `extract_model_size` ([lines 75-88](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/estimate_cost.py#L75-L88)) parses the full model repository name to extract size identifiers, falling back to `1.0B` parameters when no size tag is detected.

### Training Time Calculation

The `estimate_training_time` function implements an empirical formula based on baseline performance metrics:

```python
base_time_per_1k_examples = 0.1  # hours for a 1B model on a10g-large

time = base_time_per_1k_examples * model_params * (dataset_size/1000) * epochs
time *= hardware_multipliers.get(hardware, 1.0)

```

The `hardware_multipliers` table ([lines 50-58](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/estimate_cost.py#L50-L58)) scales the baseline time relative to `a10g-large` performance. Faster GPUs like `a100-large` use multipliers less than 1.0 to reduce estimated hours.

### Cost Computation and Safety Buffers

After calculating raw training hours, the script multiplies by the hourly rate from `HARDWARE_COSTS` to determine the estimated dollar cost. It then applies a **30% buffer** to compute `recommended_timeout_hours`, preventing job failures from unexpected slowdowns or checkpointing overhead.

The user-facing output includes:
- Parsed model and dataset metadata
- Estimated training duration in hours
- Projected cost in USD
- Recommended timeout with buffer
- Actionable warnings (e.g., "Long training time - consider faster hardware")

Finally, the script generates a ready-to-use `hf_jobs("uv", ...)` configuration snippet that users can paste directly into Claude Code to submit the job.

## Running the Estimator from the Command Line

Execute the cost estimator using `uv` to ensure dependencies are available:

```bash
uv run skills/hugging-face-model-trainer/scripts/estimate_cost.py \
  --model Qwen/Qwen2.5-0.5B \
  --dataset trl-lib/Capybara \
  --hardware a10g-large \
  --dataset-size 16000 \
  --epochs 3

```

**Example output:**

```

📊 Model: Qwen/Qwen2.5-0.5B (~0.5B parameters)
📦 Dataset: trl-lib/Capybara (~16000 examples)
🔄 Epochs: 3
💻 Hardware: a10g-large

⏱️  Estimated training time: 24.0 hours
💰 Estimated cost: $120.00
⏰ Recommended timeout: 31h (with 30% buffer)

⚠️  Long training time - consider:
   - Using faster hardware
   - Reducing epochs
   - Using a smaller dataset subset for testing

```

The estimator also prints a job configuration snippet compatible with the `hf_jobs` MCP tool.

## Integrating Cost Estimates into Job Submissions

Use the estimator's output to programmatically configure Hugging Face Jobs submissions via the `hf_jobs` helper:

```python
from huggingface_hub import hf_jobs  # MCP tool wrapper

# Configuration derived from estimate_cost.py output

job_cfg = {
    "script": """

# /// script

# dependencies = ["trl>=0.12.0", "peft>=0.7.0", "trackio"]

# ///

import trackio

# ... your training code here ...

""",
    "flavor": "a10g-large",           # from --hardware argument

    "timeout": "31h",                 # from recommended_timeout_hours

    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
}

# Submit the job with validated cost and timeout parameters

hf_jobs("uv", job_cfg)

```

This integration ensures you never submit jobs with insufficient timeout buffers or unexpectedly expensive hardware configurations.

## Summary

- The **[`estimate_cost.py`](https://github.com/huggingface/skills/blob/main/estimate_cost.py)** script in `hugging-face-model-trainer` provides pre-submission cost and runtime projections for Hugging Face training jobs.
- It calculates expenses using **hardware cost tables** (`HARDWARE_COSTS`) and **model size detection** (`MODEL_SIZES` with `extract_model_size`).
- Training time estimates rely on an **empirical formula** with `hardware_multipliers` relative to an `a10g-large` baseline.
- The script adds a **30% safety buffer** to compute recommended timeouts, preventing job failures from checkpointing overhead.
- Output includes actionable warnings and a ready-to-use **`hf_jobs`** configuration snippet for immediate submission.

## Frequently Asked Questions

### How does the script determine the model size for cost estimation?

The `extract_model_size` function ([lines 75-88](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/estimate_cost.py#L75-L88)) parses the model repository name for size indicators like `0.5B` or `7B`, then maps these through the `MODEL_SIZES` dictionary ([lines 30-37](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/estimate_cost.py#L30-L37)) to billions of parameters. If no size tag is found, it defaults to `1.0B` parameters to ensure conservative estimates.

### What hardware configurations are supported by the cost estimator?

The estimator supports all GPU flavors defined in the `HARDWARE_COSTS` dictionary ([lines 18-28](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/estimate_cost.py#L18-L28)), including `a10g-large`, `a100-large`, and other common Hugging Face Jobs compute tiers. Each entry maps to a specific hourly USD rate and has a corresponding entry in the `hardware_multipliers` table ([lines 50-58](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/estimate_cost.py#L50-L58)) that adjusts training time estimates relative to the baseline performance.

### How is the recommended timeout calculated?

The script first calculates raw training hours using the empirical formula involving model parameters, dataset size, epochs, and hardware multipliers. It then multiplies these hours by the hardware's hourly rate from `HARDWARE_COSTS` to determine cost. Finally, it applies a **30% buffer** to the estimated duration to generate `recommended_timeout_hours`, ensuring the job has adequate time for checkpointing, data loading overhead, and unexpected slowdowns without incurring unnecessary compute costs from excessive timeouts.

### Can I use the cost estimator for custom training scripts not in the repository?

Yes, while [`estimate_cost.py`](https://github.com/huggingface/skills/blob/main/estimate_cost.py) lives in the `hugging-face-model-trainer` skill, it functions as a standalone CLI tool that accepts any model identifier from the Hugging Face Hub and arbitrary dataset sizes. You can run the estimator independently to generate cost projections and timeout recommendations, then apply those values to any custom training job configuration submitted via `hf_jobs`, regardless of whether you use the skill's provided training templates or your own scripts.