gitwtfhub

wtf is alignment-handbook?

huggingface/alignment-handbook — explained in plain English

Analysis updated 2026-06-26

5,598PythonAudience · researcherComplexity · 5/5Setup · hard

TL;DR

The Alignment Handbook provides ready-to-run training scripts and YAML config files for turning a base language model into a helpful assistant using instruction fine-tuning and preference alignment techniques like DPO and ORPO.

Mindmap

mindmap
  root((alignment-handbook))
    Training stages
      Supervised fine-tuning
      Preference alignment
      Continued pretraining
      Reward modeling
    Techniques
      DPO
      ORPO
      LoRA
      QLoRA
    Infrastructure
      DeepSpeed
      Multi-GPU
      CUDA
      Flash Attention 2
    Recipes
      Zephyr series
      SmolLM

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Fine-tune a base language model on your own instruction dataset to create a custom assistant.

REASON 2

Reproduce the Zephyr or SmolLM models from scratch using the provided YAML recipes.

REASON 3

Adapt a language model to a new language or specialized domain with continued pretraining scripts.

REASON 4

Run preference alignment with DPO or ORPO on a single GPU using LoRA for parameter-efficient training.

What's in the stack?

PythonPyTorchDeepSpeedCUDAFlash Attention 2

How it stacks up

huggingface/alignment-handbookvibora-io/viboramodelscope/funclip
Stars5,5985,5985,599
LanguagePythonPythonPython
Setup difficultyhardeasymoderate
Complexity5/53/52/5
Audienceresearcherdevelopergeneral

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · hard Time to first run · 1day+

Requires Python 3.11, a GPU with matching CUDA version, Flash Attention 2, and a base model downloaded separately.

Wtf does this do

The Alignment Handbook is a collection of training recipes published by Hugging Face for turning a base language model into a helpful, safe assistant. A base language model is trained to predict text but does not know how to follow instructions or have a conversation. Alignment is the process of further training that model to behave the way users and developers want, for example by following instructions, avoiding harmful responses, or adopting a particular tone. The repository provides scripts and configuration files that cover the main stages of this process. The first stage is supervised fine-tuning, where the model learns to follow instructions by training on examples of good responses. The second stage is preference alignment, where the model learns to prefer better responses over worse ones using techniques called DPO (Direct Preference Optimisation) and ORPO. The repository also includes scripts for continued pretraining, which is useful for adapting a model to a different language or a specialized domain, and for reward modeling. Each recipe is a YAML configuration file that captures all the settings for a single training run. The repository ships recipes for several publicly known models, including the Zephyr series and SmolLM. These recipes let researchers reproduce those models or adapt the configurations for their own training runs. The scripts support distributed training across multiple GPUs using a library called DeepSpeed, as well as lighter-weight parameter-efficient fine-tuning approaches called LoRA and QLoRA that work on smaller hardware. Installation requires Python 3.11, a specific version of PyTorch matched to the CUDA version on your machine, and Flash Attention 2. The project is developed by the Hugging Face H4 team and is intended for researchers and engineers who want to train their own aligned language models rather than just use existing ones. The full README is longer than what was shown.

Yoink these prompts

Prompt 1
I want to fine-tune a base language model to follow instructions using the Alignment Handbook. What hardware do I need and which YAML recipe should I start with?
Prompt 2
How do I modify an Alignment Handbook recipe to use LoRA instead of full fine-tuning so it fits on a single consumer GPU?
Prompt 3
Walk me through adapting the Zephyr recipe in the Alignment Handbook to train on my own dataset in a different language.
Prompt 4
What is DPO and how does the Alignment Handbook use it to teach a model to prefer better responses over worse ones?
Prompt 5
How do I set up DeepSpeed distributed training across multiple GPUs using the Alignment Handbook training scripts?

Frequently asked questions

wtf is alignment-handbook?

The Alignment Handbook provides ready-to-run training scripts and YAML config files for turning a base language model into a helpful assistant using instruction fine-tuning and preference alignment techniques like DPO and ORPO.

What language is alignment-handbook written in?

Mainly Python. The stack also includes Python, PyTorch, DeepSpeed.

How hard is alignment-handbook to set up?

Setup difficulty is rated hard, with roughly 1day+ to a first successful run.

Who is alignment-handbook for?

Mainly researcher.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.