Llama 4 ships as two gated Mixture-of-Experts models — Scout (17B active / ~109B total parameters, 16 experts) and Maverick (17B active / ~400B total parameters, 128 experts) — and you must accept Meta's Llama 4 Community License on Hugging Face before any fine-tuning code will run.
LoRA or QLoRA, not full fine-tuning, is the realistic path for almost everyone. Full-parameter fine-tuning of a 109B–400B-parameter MoE model needs multi-node H100 clusters; LoRA only trains a small set of adapter weights and fits on far less hardware.
The current stack is transformers (v4.51.0 or newer) plus peft and trl, with bitsandbytes added for 4-bit quantized (QLoRA) training; all four install from PyPI under those exact package names.
Meta's own fine-tuning guidance lists four supported approaches — full fine-tuning, LoRA, QLoRA, and reinforcement learning — and points to torchtune, Hugging Face PEFT, Axolotl, or Unsloth as the tooling, not a single blessed script.
Scout can run inference in int4 on a single H100 GPU, but that figure describes inference, not training; LoRA fine-tuning still needs enough VRAM to hold the frozen base weights plus optimizer state for the adapter layers, which is why most public walkthroughs quantize the base model first.
The dataset you fine-tune on matters as much as the training code, and teams building instruction-tuning or RAG-grounding datasets from the public web often hit the same wall as scraping projects: rate limits, JavaScript-rendered pages, and geo-restricted sources.
This guide labels every code block honestly — illustrative or config-only where syntax is verified against current docs but not run against real weights, and where GPU access and an accepted Llama 4 license are required and unavailable here.
Introduction: what fine-tuning Llama 4 actually requires
Fine-tuning Llama 4 means adapting one of Meta's two released checkpoints, Llama 4 Scout or Llama 4 Maverick, on a smaller task-specific or domain-specific dataset instead of training a model from scratch. Both are Mixture-of-Experts (MoE) architectures rather than the dense transformers of Llama 2 and Llama 3: Scout activates 17 billion parameters out of roughly 109 billion total across 16 experts, and Maverick activates 17 billion parameters out of roughly 400 billion total across 128 experts, according to Meta's own model documentation and the Hugging Face Llama 4 release post. That total-parameter count is the number that matters for fine-tuning decisions, because even LoRA fine-tuning has to load the full set of expert weights into memory before it freezes them.
Both models are gated on Hugging Face. You accept the custom Llama 4 Community License Agreement — which requires a name, date of birth, and organization, and adds a separate licensing requirement if your product exceeds 700 million monthly active users — before Hugging Face grants download access, as documented on the Llama-4-Scout-17B-16E-Instruct model card. This guide uses the library-tutorial format built around Hugging Face's transformers, peft, and trl libraries, since that combination is the one Meta's own fine-tuning documentation lists first and the one with the most current, verifiable package metadata. If terms like MoE, LoRA, or context window are unfamiliar, Nstdata's data extraction glossary covers adjacent data-collection and AI-pipeline terminology used throughout this guide.
Take a Quick Look
Building a custom instruction-tuning dataset for Llama 4 often means pulling text from thousands of public pages first — Nstdata Crawl turns that URL list into clean Markdown or JSON in one API call instead of a custom scraper.
Installing the Llama 4 fine-tuning stack means adding four PyPI packages on top of a CUDA-enabled PyTorch environment: transformers, peft, trl, and bitsandbytes. As of this writing, pip install --dry-run against the live PyPI index resolves transformers 5.15.1, peft 0.20.0, trl 1.10.0, bitsandbytes 0.50.1, and accelerate 1.14.0 — all real, current releases, not placeholder version numbers.
## config-only: package names and version resolution verified live against PyPI on 2026-08-20;## not run against a GPU runtime or real model weights (prerequisite-gap, see Honest limits).pip install"transformers>=4.51.0" peft trl bitsandbytes accelerate datasets
Meta's own requirement, stated on the Llama 4 Hugging Face release post, is transformers version 4.51.0 or newer for Llama 4 support, since earlier releases do not include the MoE and early-fusion multimodal code paths Llama 4 needs. The peft package on PyPI supplies the LoRA adapter classes (LoraConfig, TaskType.CAUSAL_LM) and the trl package on PyPI supplies SFTTrainer, the trainer class most current supervised fine-tuning guides build on. bitsandbytes is only required if you quantize the base model to 4-bit or 8-bit for QLoRA; a full-precision or bf16 LoRA run does not need it.
Meta's official fine-tuning how-to guide lists this same transformers/peft/trl path alongside torchtune, Axolotl, and Unsloth as supported approaches, rather than endorsing one tool exclusively — pick based on which stack's current documentation best matches your target hardware.
Before any of this runs, authenticate with Hugging Face and accept the Llama 4 license on the model page — huggingface-cli login (or HF_TOKEN in the environment) is what turns a 401 "gated repo" error into a successful download.
Configure: LoRA and quantization settings for Llama 4
Configuring Llama 4 for fine-tuning means choosing a LoRA rank, target modules, and (optionally) a quantization config before you ever touch the trainer. The peft library's LoraConfig takes the same arguments for Llama 4 as for any other causal language model, because LoRA attaches to linear layers by name rather than depending on the base model's architecture:
## config-only: argument names verified against the current PEFT 0.20.0 documentation;## not executed against downloaded Llama 4 weights (prerequisite-gap).from peft import LoraConfig, TaskType
lora_config = LoraConfig( r=16, lora_alpha=32, lora_dropout=0.05, bias="none", task_type=TaskType.CAUSAL_LM, target_modules=["q_proj","k_proj","v_proj","o_proj"],)
For quantized (QLoRA-style) training, pair that with a BitsAndBytesConfig passed to from_pretrained when loading the base model:
## config-only: BitsAndBytesConfig fields verified against bitsandbytes 0.50.1 and## transformers 5.15.1 documentation; not executed against real weights (prerequisite-gap).from transformers import BitsAndBytesConfig
import torch
bnb_config = BitsAndBytesConfig( load_in_4bit=True, bnb_4bit_quant_type="nf4", bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True,)
Llama 4 Scout's own model card notes that the model "can fit within a single H100 GPU with on-the-fly int4 quantization" for inference — a useful reference point, but not a training figure. LoRA training adds optimizer state for the adapter parameters and activation memory for backpropagation on top of that footprint, so treat any single-GPU claim you see for Llama 4 fine-tuning as needing its own verification against your exact batch size, sequence length, and target-module list before you rely on it.
Basic implementation: a supervised fine-tuning run with TRL
Running a basic Llama 4 fine-tune with TRL means loading the gated base model, wrapping it with the LoRA config, and handing both to SFTTrainer along with a formatted dataset. TRL's SFTTrainer accepts a Hugging Face Dataset object and a peft_config argument directly, so the LoRA wrapping happens inside the trainer rather than as a separate step:
## prerequisite-gap: requires an accepted Llama 4 license grant on Hugging Face and a## multi-GPU / H100-class runtime not available in this environment. Class names, method## names, and argument shapes (SFTTrainer, peft_config, dataset_text_field) verified## against the live trl 1.10.0 and transformers 5.15.1 package documentation.from datasets import load_dataset
from transformers import AutoModelForCausalLM, AutoTokenizer
from trl import SFTTrainer, SFTConfig
model_id ="meta-llama/Llama-4-Scout-17B-16E-Instruct"tokenizer = AutoTokenizer.from_pretrained(model_id)model = AutoModelForCausalLM.from_pretrained( model_id, quantization_config=bnb_config, device_map="auto",)dataset = load_dataset("json", data_files="train.jsonl", split="train")training_args = SFTConfig( output_dir="./llama4-scout-lora", per_device_train_batch_size=1, gradient_accumulation_steps=16, num_train_epochs=3, learning_rate=2e-4, bf16=True, logging_steps=10,)trainer = SFTTrainer( model=model, args=training_args, train_dataset=dataset, peft_config=lora_config,)trainer.train()
The dataset format expected here is a JSON Lines file where each line is a chat-formatted example — typically a messages field with role/content pairs matching Llama 4's chat template, or a plain text field if you pre-render the prompt yourself. SFTTrainer applies the tokenizer's chat template automatically when a messages field is present, which avoids a common source of silent formatting bugs: training on text that doesn't match the exact special-token layout the base model was instruction-tuned with.
Advanced patterns: sourcing and preparing your fine-tuning dataset
Advanced Llama 4 fine-tuning work spends more engineering time on the dataset than on the trainer call above, because LoRA hyperparameters are largely fixed once you've picked a rank and target modules, while dataset quality directly determines whether the adapter generalizes. Two dataset patterns come up repeatedly for domain-specific Llama 4 fine-tunes: instruction pairs distilled from a larger model, and retrieval-grounded examples built from a team's own document or web corpus.
For the second pattern — building an instruction-tuning or RAG-grounding dataset from public web sources — the same operational problems that affect general web scraping apply directly: pages that render content client-side with JavaScript, IP-based rate limiting once you're pulling thousands of pages, and country-specific content that only resolves correctly from an IP in that region. This is where a web-data API or proxy layer becomes a practical prerequisite rather than an unrelated tool. Nstdata Crawl is an AI-oriented web crawling API built for exactly this kind of bulk collection: it takes a URL or a site-level crawl job and returns Markdown, cleaned HTML, or JSON, with JavaScript rendering and proxy-backed access handled behind the API rather than in your own scraper code. It fits teams building fine-tuning corpora, RAG knowledge bases, or any dataset that starts as "several thousand public pages" rather than a single curated file, and the tradeoff to weigh against it is the same as any hosted crawling service — you're billed per successful page fetch (including non-2xx responses that still returned a page) rather than per attempt, so unbounded or poorly-scoped crawl jobs cost more than a tightly-scoped one.
Site-level crawling with depth and page limits — a crawl job accepts maxDepth, maxPages, and include/exclude URL rules, which keeps a documentation site or blog crawl from wandering into search results, pagination, or login pages while you're assembling training text.
Multiple output formats per request — the same crawl can return Markdown for LLM training text, JSON for structured metadata, and a screenshot for manual QA, without three separate scraping passes.
Proxy-backed, JavaScript-rendered fetches — pages that only render their real content client-side, or that block bare requests-style traffic, are fetched through a real browser and Nstdata's own proxy pool rather than failing silently in a plain HTTP client.
For teams that already run their own scraping code and only need reliable, geo-diverse egress IPs to reach rate-limited or region-locked sources during dataset collection, Nstdata's Residential Lite Proxies pricing serve the same underlying need without the hosted-crawling layer on top. The Nstdata Crawl API documentation covers the exact request and response shape for site-level crawl jobs if you go that route instead, and the same reliability problem — keeping a data-collection pipeline running under an AI workload — is the subject of Nstdata's write-up on building a stable web data layer for AI agents and RAG systems. Either path is a data-collection decision made before fine-tuning starts, not a fine-tuning library choice, so evaluate it against how much of your dataset work is "fetch pages" versus "parse and structure content you already have."
Honest limits: where this stack stops
The Hugging Face transformers/peft/trl stack stops short of making Llama 4 fine-tuning accessible on consumer hardware, and no verified source reviewed for this article claims otherwise. Full-parameter fine-tuning of Maverick's roughly 400 billion total parameters requires the kind of multi-node H100 cluster Meta itself used for pretraining — Meta's Llama 4 documentation reports 5.0 million GPU-hours on H100s for training, which is a pretraining figure, not a fine-tuning one, but it signals the scale this architecture assumes. LoRA and QLoRA substantially reduce trainable-parameter count and optimizer memory, but the frozen base weights for Scout (109B total) or Maverick (400B total) still have to be loaded, quantized or not.
Unsloth publishes inference-time VRAM figures for aggressively quantized Llama 4 GGUF builds — a 1.78-bit Scout build reportedly fits a 24GB GPU, and a 1.78-bit Maverick build reportedly needs two 48GB GPUs, per Unsloth's own Llama 4 documentation — but that page, as fetched for this article, covers those numbers for running inference rather than for fine-tuning throughput, so this guide does not restate them as fine-tuning requirements. If Unsloth ships Llama-4-specific fine-tuning notebooks with verified training VRAM numbers, check its current documentation directly rather than relying on an inference figure as a training estimate.
Every training code block above is labeled prerequisite-gap: this article verified package names, class names, and argument shapes against the live PyPI and package documentation for transformers, peft, trl, and bitsandbytes, but did not execute the training loop, because that requires an accepted Llama 4 license grant on Hugging Face and GPU hardware neither of which is available in this writing environment. Anyone reproducing the code should expect to spend real time on out-of-memory tuning (batch size, gradient accumulation, sequence length) before a run completes successfully.
Troubleshooting: common Llama 4 fine-tuning errors
A 401 or "gated repo" error on from_pretrained almost always means the Hugging Face account hasn't accepted the Llama 4 Community License yet, or huggingface-cli login wasn't run before the script executed — accepting the license on the model page and re-authenticating resolves it. A CUDA out-of-memory error during the first training step is normal on an under-sized GPU; reduce per_device_train_batch_size to 1, increase gradient_accumulation_steps to compensate, shorten the maximum sequence length, or add 4-bit quantization via BitsAndBytesConfig before assuming the hardware is simply insufficient. A trainer that runs but produces incoherent outputs after fine-tuning usually points to a chat-template mismatch — verify that training examples use the same role/content structure and special tokens that AutoTokenizer.apply_chat_template produces for the base model, rather than a hand-written prompt format that only approximates it. A peft/trl version conflict (an import error naming SFTConfig or a changed LoraConfig field) means the installed versions predate the code shown here; re-run the install command above to pull current releases rather than patching around an old API.
Conclusion
Fine-tuning Llama 4 today means accepting Meta's gated license, picking Scout over Maverick unless you have a real multi-GPU H100 budget, and building the training loop on transformers, peft, and trl rather than a single all-in-one script. The mechanics — LoRA config, quantization, SFTTrainer — are straightforward and well-documented; the harder work is almost always the dataset the LoRA adapter learns from, whether that's synthetic instruction pairs or a corpus pulled from thousands of public pages.
FAQ
Q: Do I need a GPU to fine-tune Llama 4?
Yes — Llama 4 Scout alone has roughly 109 billion total parameters, so both LoRA and full fine-tuning require a CUDA GPU with substantial VRAM; there is no practical CPU-only fine-tuning path for this model family. Cloud GPU rental (a single H100 or multi-GPU node, depending on method) is the realistic option for most individuals and small teams.
Q: Is Llama 4 free to fine-tune and use commercially?
Llama 4 is available under Meta's custom Llama 4 Community License Agreement, which is not the same as a fully open-source license — it requires accepting terms on Hugging Face before download, and it adds a separate licensing requirement for products or services with more than 700 million monthly active users. Read the exact license text on the model card before committing to commercial use.
Q: What's the difference between LoRA and full fine-tuning for Llama 4?
LoRA fine-tuning trains a small set of added adapter weights while keeping the base model's roughly 109B (Scout) or 400B (Maverick) parameters frozen, which drastically cuts trainable-parameter count and optimizer memory compared with full fine-tuning, which updates every parameter in the base model. Full fine-tuning at this scale needs a multi-node GPU cluster; LoRA is the method nearly every publicly documented Llama 4 fine-tuning walkthrough actually uses.
Q: Which library should I use to fine-tune Llama 4?
Hugging Face's transformers (version 4.51.0 or later) combined with peft for LoRA and trl for the SFTTrainer training loop is the combination Meta's own fine-tuning documentation lists alongside torchtune, Axolotl, and Unsloth as supported tooling. Pick whichever of these has the most current, verified documentation for your exact use case rather than assuming any one tool is universally faster.
Q: Why does loading Llama 4 fail with a gated-repository or 401 error?
That error means the Hugging Face account running the script hasn't accepted the Llama 4 Community License on the model page yet, or the session isn't authenticated with a valid token. Accept the license on huggingface-cli login (or set an HF_TOKEN environment variable) after accepting the license, then retry.
Q: Can I fine-tune Llama 4 Maverick on a single GPU?
Not for a meaningful fine-tuning run — Maverick's roughly 400 billion total parameters across 128 experts is far larger than Scout's 109 billion, and no verified source reviewed for this guide claims single-GPU fine-tuning is feasible for Maverick even with LoRA and 4-bit quantization. Most public Llama 4 fine-tuning examples target Scout specifically for this reason.
Q: Does the training dataset format matter for Llama 4 fine-tuning?
Yes — SFTTrainer expects either a messages field formatted as role/content chat turns, which it renders through the tokenizer's chat template automatically, or a pre-rendered text field, and mismatching this format against Llama 4's actual chat template is a common cause of incoherent post-training outputs. Verify your formatted examples against AutoTokenizer.apply_chat_template output before starting a full run.
Lena Zhou
Oct. 21st 2026
Experience Nstdata - Start Your Free Trial Today
110M+ real IPs with 99.9% access success
Get immediate access to premium residential, datacenter, IPv6 and ISP proxy pools.
Blazing-fast average response ~0.5s for high-concurrency tasks
