unslothai/notebooks: Fine-Tuning and RL Notebooks for Text, Vision, Audio and TTS Models

What unslothai/notebooks solves and who it is for

Fine-tuning a language model usually starts with the same unglamorous work: pick a base model that fits your GPU, format a dataset into the right chat template, set LoRA rank and sequence length, then wire up a trainer. Every step has a failure mode that produces a confusing error rather than a clear one. unslothai/notebooks is a collection of notebooks that already contain those decisions for a specific model, so the first run is a matter of opening a notebook and executing cells rather than assembling a training script from scratch.

The README describes the collection as Colab notebooks organized by model, and states that the notebooks run locally and feature data prep, training and inference. The description puts the count at 250+ notebooks covering text, vision, audio, embedding and TTS models. The table in the README lists entries such as gpt-oss (20B) Fine-tuning, gpt-oss (20B) GRPO, Qwen3 (14B) Reasoning Conversational, Qwen3-VL (8B) Vision, Qwen3-Embedding (0.6B), Gemma 3 (4B) Vision, Gemma 3N (4B) Audio, EmbeddingGemma (300M), Ministral 3 VL (3B) Vision, Llama 3.1 (8B) Alpaca, Phi-4 (14B) Conversational and Orpheus (3B) TTS.

The audience is narrow and worth naming. This is for someone who has a target model in that table and wants a working loop today. It is not for someone who needs a supported library with semantic versioning, because the repository ships notebooks and generator scripts, not an importable package.

How the notebooks are organized and generated

The repository is a flat layout rather than a Python package. Top-level entries include nb/, scripts/, tests/, python_scripts/, kaggle/, molab/, original_template/, Template_Notebook.ipynb, update_all_notebooks.py, update_max_seq_length.py and replace_text.py. The notebooks themselves live under nb/, which is where the Colab links in the README point.

The README contains an explicit marker around the notebook link tables: a comment states that the section is generated by update_all_notebooks.py and must not be edited manually. That tells you the tables are derived from the notebook files, so adding a notebook means running the generator rather than editing the README by hand. The same pattern appears in the pyproject.toml comments, which describe scripts/molab_generate.py as emitting marimo.App cells and running ruff format as a final pass.

There is a second output target. The molab/ directory and the generator optional dependency suggest notebooks are also emitted in marimo form, and the pyproject comments mention CI tests named test_molab_marimo_validity.py and test_molab_generation_parity.py. The pins on marimo and ruff are deliberate: the comment explains that marimo stamps its version into __generated_with, so any release drifts parity, and that the pins should be bumped together with a regeneration commit. If you fork this repository and regenerate, that pinning rule is the one to respect.

Installing the repository tooling and running a first notebook

The notebooks are meant to be opened, not installed as a dependency. The README's primary call to action is an Open in Colab badge pointing at nb/gpt-oss-(20B)-Fine-tuning.ipynb, and the documentation link points to unsloth.ai/docs/get-started/unsloth-notebooks. For local work, the repository does provide a Python project definition for the tooling around the notebooks.

The pyproject.toml requires Python 3.13 or newer and lists three base dependencies: ipykernel, ipywidgets and nbconvert. Installing the project in editable mode gives you the environment needed to execute notebooks locally.

pip install -e .

The repository also defines a generator extra for the scripts that produce notebook variants. The pyproject comments describe marimo as used by scripts/molab_generate.py and by CI, and ruff as invoked by that script as a final formatting pass.

pip install -e ".[generator]"

After that, the practical first use is to open a notebook from nb/ that matches your hardware and run its cells in order. The README states that the notebooks cover data prep, training and inference, so expect the early cells to load and format a dataset, the middle cells to configure and run training, and the later cells to run generation against the trained adapter. The generator scripts are separate from that path; tests/ and python_scripts/ exist for maintaining the collection, not for training.

Where the notebook approach breaks down

A notebook is a snapshot, and this collection is a snapshot of many models at once. The README table names specific model versions, including Gemma 4, Qwen3.5 and Ministral 3. Model identifiers, chat templates and library APIs change, and a notebook that pins an older identifier will fail at the load step rather than at training. Nothing in the README describes a deprecation policy or a compatibility matrix, so the only way to know whether a given notebook still runs is to try it.

The repository also has no released versions. The pyproject.toml sets version 0.1.0 and its description field still reads "Add your description here", which is a fair signal of how much the packaging layer is treated as an afterthought. There is no changelog in the repository and no release artifacts, so pinning to a tag is the only reproducible option, and the repository does not show which tags exist.

There is a licensing boundary worth noting without giving legal advice. The repository is LGPL-3.0. That covers the repository contents, not the model weights the notebooks download, which carry their own terms. If you plan to redistribute a fine-tuned model, the base model's licence is the one that governs, and the README does not summarize those terms.

Finally, this is the wrong tool if your target model is not in the table. The notebooks are per-model by design; there is no generic trainer that adapts to an arbitrary architecture.

How this differs from writing your own training script

The alternative most engineers reach for is a training library used directly, writing a script that configures a trainer, a LoRA configuration and a dataset formatter themselves. The difference is where the knowledge lives. With a library you get an API surface that is documented and versioned, and you own the model-specific details. With these notebooks the model-specific details are already written down, including the chat template and the training arguments, but there is no API contract and no version to pin against.

That trade favors exploration over production. If you are evaluating whether a 4B vision model can handle your task, copying the Qwen3-VL (8B) Vision or Gemma 3 (4B) Vision notebook and swapping the dataset gets you an answer faster than reading trainer documentation. If you are building a pipeline that must run unattended every night, the notebook is a prototype and the script is the deliverable. The repository's own generator tooling makes the same distinction: it treats notebooks as generated artifacts with parity tests, not as the product.

Maintenance cost and what to verify before adopting

The last push to the default branch was on 2026-09-22, and the repository is not archived, so the collection is being updated. That matters because the value of a notebook collection is entirely in whether the notebooks still execute against current model and library versions.

Upgrade cost sits in two places. The generator extra pins marimo==0.23.8 and ruff==0.15.16, and the pyproject comments state that the pins must be bumped together with a regeneration commit because marimo stamps its version into the generated file. If you maintain a fork, a marimo upgrade is a regeneration event, not a dependency bump. The second cost is Python: requires-python is >=3.13, so an environment on 3.12 will not install the project tooling even though the notebooks themselves may run in Colab.

The licence is LGPL-3.0. If you copy notebook code into a larger application, the terms of that licence apply to the copied code, and the model weights downloaded by the notebooks are governed separately by their own licences. The README does not list those licences per model.

Editorial conclusion

Adopt unslothai/notebooks if you want a runnable fine-tuning or GRPO loop for a specific Unsloth-supported model and are willing to read the notebook before running it. Do not adopt it if you need a versioned Python package, a stable API surface, or notebooks for models outside the table. Before using any notebook, open it and check which model id, dataset and training arguments it pins, then confirm that the notebook's Python version matches the repository's requires-python of >=3.13.

Frequently asked questions

Official sources

1. Issues
2. License: LGPL-3.0
3. Project website
4. README
5. unslothai/notebooks on GitHub