huggingface/smol-course: a hands-on path to aligning SmolLM3 and SmolVLM2

What smol-course actually is, and who it is for

This is a course, not a package. The README describes it as "a practical course on aligning language models for your specific use case," and the repository layout backs that up: units/, notebooks/, a leaderboard directory, a v1 directory holding the first version, and a pyproject.toml whose only purpose is to pin the dependencies the notebooks import. There is no importable smol_course module to install into an application.

The audience is narrow and stated plainly. Prerequisites are a basic understanding of machine learning and natural language processing, plus familiarity with Python, PyTorch and the transformers library, plus access to a pre-trained model and a labeled dataset. If you have never fine-tuned anything, the first unit will be steep; if you have fine-tuned large models on rented clusters and want to see what changes when the model is small, this is the right shape of material.

The stated draw is that "everything runs on most local machines," with minimal GPU requirements and no paid services. That constraint shapes every unit: the models are SmolLM3 and SmolVLM2, and the README notes the skills transfer to larger models or other small LLMs and VLMs. The course outline lists seven topics, of which four are marked released: Instruction Tuning, Evaluation, Preference Alignment and Vision Language Models. Reinforcement Learning is listed for October 2025, Synthetic Data for November 2025, and an Award Ceremony for December 2025.

How the units, notebooks and leaderboard fit together

The mechanism is a loop rather than a pipeline. The README's participation steps are: follow the Hugging Face Hub org at huggingface.co/smol-course, read the material and do the exercises, submit a model to the leaderboard, then climb the leaderboard. The leaderboard directory in the repository is the artifact behind that last step, and the course is described as open and peer reviewed, with contributions arriving as pull requests.

That means the data flow is deliberately manual. You read a unit, run its notebook against a labeled dataset you supply, produce a fine-tuned model, and push it to the Hub so it can be scored. Nothing in the repository automates the submission for you, and the README does not document the submission format or the scoring harness. If you want to know how the leaderboard evaluates a model, the README is silent; the leaderboard directory is where that answer would have to live.

The dependency set tells you what the notebooks lean on. The pyproject.toml pins datasets, huggingface-hub, lighteval, ipywidgets, transformers, trl and bitsandbytes, with Python 3.11 or newer required. lighteval covers the Evaluation unit's benchmarks, trl covers supervised fine-tuning and DPO-style preference alignment, and bitsandbytes is what makes quantized local training plausible on modest hardware. requirements.txt is an exported lockfile generated by uv, and it carries the CUDA wheels for x86_64 Linux, which is a hint about the environment the export was produced in rather than a hard requirement.

Installing the environment and running your first unit

The repository does not ship an install section in the README, so the honest starting point is the dependency files themselves. Python 3.11 or newer is required by pyproject.toml. The lockfile header shows it was produced with uv, so uv is the path of least resistance, though plain pip against requirements.txt should also resolve.

Clone the repository and create an environment with the pinned dependencies:

git clone https://github.com/huggingface/smol-course.git
cd smol-course
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On Windows the activation line differs, and requirements.txt already carries a colorama marker for platform_system == 'Windows', which suggests the export was checked against that platform. After installation, the notebooks under notebooks/ and the unit material under units/ are what you open. The README does not name a specific first notebook, so pick the Unit 1 material on instruction tuning.

If you prefer to work from the declared dependencies rather than the lockfile, the project metadata is the source of truth:

pip install "datasets>=3.1.0" "huggingface-hub>=0.26.3" "lighteval>=0.6.2" \
  "ipywidgets>=8.1.5" "transformers>=4.46.3" "trl>=0.12.1" "bitsandbytes>=0.45.0"

That set is what the units assume. lighteval is the one to watch: it pulls its own evaluation stack, and it is the heaviest dependency in the list for anyone who only wants the fine-tuning units.

Where the course thins out: unfinished units and undocumented scoring

Two gaps matter before you commit time. The first is coverage. The outline marks Reinforcement Learning as October 2025 and Synthetic Data as November 2025, so at the time of writing those topics are planned rather than released. Anyone arriving for RLHF-style work will find the preference alignment unit on DPO but not the reinforcement learning unit the outline promises.

The second gap is the leaderboard. The README tells you to submit a model and climb the leaderboard, but it does not document the submission format, the evaluation harness, or what a submission must contain. The leaderboard directory exists, yet the README gives no command or schema for it. Treat the leaderboard as a community mechanism you will have to reverse-engineer from the directory contents, not as a documented API.

There is also a forward-looking caveat in the README itself: the course "will soon be re-released on Hugging Face Learn." That does not invalidate the repository, but it does mean the canonical home of the material may move, and links or structure here could drift. The v1 directory preserves the previous GithHub-markdown-and-notebooks version, which is useful for diffing how the material has changed, and it is spelled that way in the README.

smol-course versus the Hugging Face smol training playbook

The obvious comparison is the Hugging Face smol training playbook, which people also search for as a PDF. The difference is in the artifact. The playbook is a written guide: you read it and apply the reasoning to your own training run. smol-course is a set of executable units with pinned dependencies and a leaderboard attached, so the feedback loop is running a notebook and submitting a model rather than reading a chapter.

That distinction decides which one you want. If your goal is to understand why a training recipe is shaped the way it is, the playbook's prose is the better fit, and a course notebook will feel like it is hiding the reasoning behind cells. If your goal is to end up with a fine-tuned SmolLM3 checkpoint and a number attached to it, the course gives you the environment, the exercises and the leaderboard, and the playbook does not. Neither replaces the other, and the course assumes you can already read PyTorch and transformers code without hand-holding.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-09-17, so the material is current. There have been no tagged releases retrieved, which fits a course: versioning happens through commits and through the v1 directory rather than through release artifacts. The pyproject.toml still carries version 0.1.0, so do not read that as a signal about the content's maturity.

Upgrade cost is real but bounded. The lockfile pins exact versions, including transformers 4.46.3, trl 0.12.1 and bitsandbytes 0.45.0, and those are the versions the notebooks were written against. Moving to newer transformers or trl releases is where breakage will come from, because training APIs in trl change between minor versions. If you want reproducibility, keep the lockfile; if you want current library behaviour, expect to fix notebook cells.

The licence is Apache-2.0, per the LICENSE file at the repository root. That is permissive and applies to the course material in this repository. It does not automatically cover the SmolLM3 and SmolVLM2 model weights the course points you at, which live on the Hugging Face Hub under their own terms; check those separately before you ship anything trained from them. This is a description of what the licence file says, not legal advice.

Editorial conclusion

Adopt smol-course if you already write Python and PyTorch and want a guided, local path through supervised fine-tuning, evaluation and preference alignment on SmolLM3 or SmolVLM2, with the v1 notebooks still available in the v1 directory for comparison. Do not adopt it if you need a supported library, a certificate, or material on reinforcement learning and synthetic data today, since the outline lists those units for October and November 2025. Before starting, verify that your Python is at least 3.11, that your GPU or CPU can hold the model you pick, and that the leaderboard submission flow described in the README is still open, because the README also states the course will soon be re-released on Hugging Face Learn.

Frequently asked questions

Official sources

1. huggingface/smol-course on GitHub
2. Issues
3. License: Apache-2.0
4. README