---

name: torchtune description: "Use torchtune for PyTorch-native LLM post-training, recipe/config workflows, datasets, models, evaluation, quantization, checkpointing, and RLHF utilities." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

torchtune

Use this repo skill when a task names torchtune, the tune CLI, torchtune recipes/configs, PyTorch-native LLM post-training, LoRA/QLoRA/DPO/PPO/KD/QAT workflows, torchtune datasets, model builders, generation, Eleuther evaluation, quantization, checkpointing, or torchtune RLHF utilities.

Torchtune development wound down in 2025, so prefer current checkout/package evidence over older examples. This skill captures the repository state in repo provenance; read it before deciding whether the skill needs refresh.

Install And Import Check

For public use, install the documented PyTorch prerequisites and torchtune package in an isolated environment:

pip install torch torchvision torchao
pip install torchtune
python - <<'PY'
import torchtune
from torchtune._recipe_registry import get_all_recipes
print("torchtune import ok", len(get_all_recipes()), "recipes")
PY
tune --help

Notes:

• torchao is required at top-level import time in this checkout; install it alongside PyTorch even though it is not listed in pyproject.toml runtime dependencies.
• Use CPU import checks for documentation/config work. Actual training, generation, evaluation, and quantization can require GPUs, large checkpoints, gated model credentials, optional packages, and explicit user approval.
• Do not import the recipes package directly. Torchtune intentionally raises from recipes/__init__.py; launch recipes through tune run, inspect with tune cat, copy with tune cp, or use registry metadata.

Route By Task

User task	Read
Use tune ls, tune cp, tune cat, tune validate, tune run, model download flags, config overrides, _component_, or registry inspection	cli-and-config
Build or validate dataset configs, message rows, prompt templates, packing, multimodal rows, preference data, or collators	data-and-datasets
Select/adapt SFT, full finetune, LoRA/QLoRA/DoRA, DPO, PPO, KD, QAT, distributed, or multi-node training recipes	post-training-recipes
Generate text, run EleutherAI evaluation, quantize checkpoints, or route trained checkpoints into eval/generation	inference-evaluation-quantization
Choose public model/tokenizer builders, PEFT modules, LoRA utilities, losses, model conversion helpers, or module APIs	models-and-modules
Debug checkpointing, precision, memory/distributed utilities, schedulers, logging/profiling, RLHF helpers, or experimental GRPO/async RL boundaries	training-utilities-and-rlhf

Safe Workflow

1. Start in cli-and-config to inspect registry names, copy configs, and build non-executing command shapes.
2. Validate data shape in data-and-datasets before wiring datasets into recipe configs.
3. Choose recipe/config families in post-training-recipes, using bundled command builders before launching expensive jobs.
4. Use models-and-modules when configs need model/tokenizer/adapter public dotpaths.
5. Use training-utilities-and-rlhf for checkpoint, dtype, distributed, logging, profiling, and RLHF runtime details.
6. After a checkpoint exists, use inference-evaluation-quantization for generation/eval/quantization plans.

Bundled Helpers

• sub-skills/cli-and-config/scripts/inspect_tune_registry.py lists built-in recipes/configs without importing recipe modules.
• sub-skills/cli-and-config/scripts/validate_config_shape.py applies torchtune-style overrides/removals and reports _component_ nodes without launching recipes.
• sub-skills/data-and-datasets/scripts/validate_messages_jsonl.py validates small JSONL message/input-output/chat/preference fixtures without importing torch.
• sub-skills/post-training-recipes/scripts/build_tune_command.py prints safe tune run training commands without executing them.
• sub-skills/inference-evaluation-quantization/scripts/build_inference_eval_command.py prints safe generate/eval/quantize commands without model work.
• sub-skills/models-and-modules/scripts/inspect_model_builders.py lists public model-family callable exports without instantiating large models.
• sub-skills/training-utilities-and-rlhf/scripts/check_training_runtime.py reports torch/CUDA/torchao/torchtune/RLHF import health without distributed initialization.

Guardrails

• Do not run training, download gated models, start distributed jobs, initialize Ray/vLLM, run Eleuther tasks, or quantize checkpoints without explicit approval and confirmed resources.
• Do not embed Hugging Face/Kaggle tokens, local cache paths, checkpoint directories, environment names, or machine-specific paths in reusable configs.
• Do not tell future agents to open or run original repo docs, tests, recipe files, or configs. Use the bundled references/scripts in this skill.
• Treat torchtune.dev and async RL/GRPO surfaces as experimental and optional-extra dependent.
• If current repo code, public configs, CLI behavior, dependencies, or docs differ from repo provenance, run refresh-repo-skill before relying on this skill.

Shared References

• Repository provenance records the source snapshot and refresh baseline.
• Routing metadata is consumed by repo-skills-router during managed import.
• Cross-cutting troubleshooting covers install/import, optional dependencies, stale registry snapshots, and known current-code issues.