torchtune: PyTorch Native Library for LLM Post-Training and Experimentation

Introduction

torchtune is a PyTorch native library designed for easily authoring, post-training, and experimenting with Large Language Models (LLMs). It provides hackable training recipes for methods like Supervised Finetuning (SFT), Knowledge Distillation (KD), Direct Preference Optimization (DPO), Proximal Policy Optimization (PPO), and Quantization-Aware Training (QAT). The library also includes simple PyTorch implementations of popular LLMs such as Llama, Gemma, Mistral, Phi, and Qwen, alongside best-in-class memory efficiency and performance improvements leveraging the latest PyTorch APIs. YAML configurations simplify the setup for training, evaluation, quantization, or inference recipes.

Important Note: As of 2025, torchtune is no longer actively maintained. For more details, please refer to The future of torchtune on GitHub.

Installation

torchtune is tested with the latest stable PyTorch release (currently 2.6.0) as well as the preview nightly version. It leverages torchvision for finetuning multimodal LLMs and torchao for the latest in quantization techniques. You should install these dependencies as well.

Install stable release

# Install stable PyTorch, torchvision, torchao stable releases
pip install torch torchvision torchao
pip install torchtune

Install nightly release

# Install PyTorch, torchvision, torchao nightlies.
pip install --pre --upgrade torch torchvision torchao --index-url https://download.pytorch.org/whl/nightly/cu126 # full options are cpu/cu118/cu124/cu126/xpu/rocm6.2/rocm6.3/rocm6.4
pip install --pre --upgrade torchtune --extra-index-url https://download.pytorch.org/whl/nightly/cpu

To confirm that the package is installed correctly, you can run the following command:

tune --help

And should see output similar to:

usage: tune [-h] {ls,cp,download,run,validate} ...

Welcome to the torchtune CLI!

options:
  -h, --help            show this help message and exit

...

Examples

To get started with torchtune, you can follow these common steps:

Downloading a model

Follow the instructions on the official meta-llama repository to ensure you have access to the official Llama model weights. Once access is confirmed, you can download the weights to your local machine, along with the tokenizer model and a responsible use guide. For Llama3.1, you can run:

tune download meta-llama/Meta-Llama-3.1-8B-Instruct \
--output-dir /tmp/Meta-Llama-3.1-8B-Instruct \
--ignore-patterns "original/consolidated.00.pth" \
--hf-token <HF_TOKEN>

Running finetuning recipes

You can finetune Llama3.1 8B with LoRA on a single GPU using the following command:

tune run lora_finetune_single_device --config llama3_1/8B_lora_single_device

For distributed training, the tune CLI integrates with torchrun. To run a full finetune of Llama3.1 8B on two GPUs:

tune run --nproc_per_node 2 full_finetune_distributed --config llama3_1/8B_full

Modify Configs

There are two ways to modify configurations:

Config Overrides

You can directly overwrite config fields from the command line:

tune run lora_finetune_single_device \
--config llama2/7B_lora_single_device \
batch_size=8 \
enable_activation_checkpointing=True \
max_steps_per_epoch=128

Update a Local Copy

You can also copy the config to your local directory and modify the contents directly:

tune cp llama3_1/8B_full ./my_custom_config.yaml
Copied to ./my_custom_config.yaml

Then, run your custom recipe by directing the tune run command to your local files:

tune run full_finetune_distributed --config ./my_custom_config.yaml

torchtune also supports finetuning on a variety of custom datasets, including instruct-style, chat-style, and preference datasets. It also supports various devices, including NVIDIA GPU, Intel XPU, AMD ROCm, Apple MPS, and Ascend NPU.

Why Use torchtune

torchtune offers several compelling features for LLM development:

• Comprehensive Post-Training Capabilities: Supports the entire post-training lifecycle with hackable recipes for Supervised Finetuning (SFT), Knowledge Distillation (KD), Reinforcement Learning from Human Feedback (RLHF) methods like DPO, PPO, GRPO, and Quantization-Aware Training (QAT).
• Extensive Model Support: Includes simple PyTorch implementations of many state-of-the-art models available on Hugging Face Hub or Kaggle Hub, such as Llama (Llama4, Llama3.3, Llama3.2-Vision, Llama3.2, Llama3.1), Mistral, Gemma2, Microsoft Phi (Phi4, Phi3), and Qwen (Qwen3, Qwen2.5, Qwen2).
• Optimized Performance and Memory Efficiency: Leverages the latest PyTorch APIs to provide best-in-class memory efficiency and performance improvements. It offers various optimization flags and techniques, such as packed datasets, torch.compile, chunked cross entropy, activation checkpointing, fused optimizer step into backward, activation offloading, and 8-bit AdamW, significantly reducing memory footprint and increasing tokens per second.
• Robust Ecosystem Integration: Focuses on integrating with popular tools and libraries, including Hugging Face Hub for model weights, EleutherAI's LM Eval Harness for evaluation, Hugging Face Datasets, PyTorch FSDP2 for distributed training, torchao for quantization, Weights & Biases and Comet for logging, ExecuTorch for on-device inference, bitsandbytes for low memory optimizers, and PEFT for continued finetuning.
• Active Community Contributions: Values and highlights contributions from its user community, fostering a collaborative development environment.

Links

• GitHub Repository: meta-pytorch/torchtune
• Official Documentation: PyTorch torchtune Documentation
• Community Discord: torchtune Discord Server
• Future of torchtune Issue: The future of torchtune