Native by default
Built on Apple’s MLX framework. Unified memory, Metal acceleration, and a workflow tuned for M-series machines.
Open source · Apple silicon native
Fine-tuning,
without the cloud.
MLX-LM-LoRA puts serious language-model adaptation on your Mac. Fast, private, and built for the silicon under your desk.
MLX-LM-LoRA is trusted by teams and industry leaders such as:
MacPawTypeFoxComputacenter
Also being used by researchers, engineers, and other professionals at Apple, IBM, Bosch, Red Hat, Hugging Face, Daimler Truck, and Mercedes-Benz Group.
A focused training stack for people who want to adapt models locally—without turning every experiment into a distributed-systems project. MLX-LM-LoRA is the code. MLX-LoRA-Studio is the calm, visual layer on top. The JOSIE model family is a production, very high-intelligence model family trained on MLX-LM-LoRA. Learn more about JOSIE ↗
Small surface.
Deep control.
Everything you need to move from dataset to adapter, with the defaults and visibility to understand what is happening.
LoRA, made legible
Low-rank adaptation with explicit configuration, checkpoints, evaluation hooks, and reproducible command-line runs.
Studio when you want it
Launch and monitor jobs through MLX-LoRA-Studio: a native interface for datasets, hyperparameters, logs, and exports.
12 training
modes.
Choose the objective that matches your data and feedback signal. These are the 12 modes exposed by the current training and MCP interfaces; GRPO variants are configured within GRPO.
SFT
Supervised fine-tuningDPO
Direct preference optimizationCPO
Contrastive preference optimizationORPO
Odds-ratio preference optimization DSLA
Directional and similarity-aware latent alignmentFTPO
Final-token preference optimizationGRPO
Group relative policy optimizationKLPO
KL-regularized policy optimization Online DPO
Online, judge-scored preference learningXPO
Exploratory preference optimizationPPO
Proximal policy optimizationRLHF REINFORCE
Reward-guided policy optimization
Supervised fine-tuningDPO
Direct preference optimizationCPO
Contrastive preference optimizationORPO
Odds-ratio preference optimization DSLA
Directional and similarity-aware latent alignmentFTPO
Final-token preference optimizationGRPO
Group relative policy optimizationKLPO
KL-regularized policy optimization Online DPO
Online, judge-scored preference learningXPO
Exploratory preference optimizationPPO
Proximal policy optimizationRLHF REINFORCE
Reward-guided policy optimization
Use supervised rows for SFT, chosen/rejected pairs for offline preference methods, and prompt/reward data for policy optimization. Check each method’s schema and active settings before starting. Read the full algorithm guides ↗
Best practice,
by method.
Start with a clean baseline, change one objective or control at a time, and evaluate held-out behavior. Each method carries a different data contract and memory profile.
SFT
Begin with NLL. Verify the chat template, end-of-turn tokens, and how much target text survives truncation. Compare validation loss and task generations; treat DFT or chunked NLL as separate experiments.
Memory Use LoRA, a small physical batch and context, and checkpointing. Chunked loss is distinct from sequential long-context execution.
DPO
Use trustworthy chosen/rejected pairs for the same prompt and keep the starting reference fixed. Start with sigmoid; track preference accuracy, reward margins, validation, and general capability.
Memory Budget a frozen reference model as well as the policy. Lower batch and context; accumulation does not shrink a physical minibatch.
CPO
Use clean same-prompt pairs and compare against SFT. Because the objective has no frozen-reference KL anchor, check held-out preferences and general capability for drift.
Memory No reference model is loaded. Pair scoring still needs activations; checkpointing and smaller batches help.
ORPO
Compare with an SFT baseline. Check pair labels and preference-score scale, then evaluate both preference quality and ordinary instruction following.
Memory Reference-free, but pair activations and logits remain. Use checkpointing and a smaller physical batch.
DSLA
First establish the corresponding plain preference baseline. Track latent and preference metrics together; select pooling, layer, and alignment variant from held-out results.
Memory Retained hidden states add activation pressure. Keep complete, short examples; sequential long-context mode is rejected for DSLA.
FTPO
Match tokenizer and chat template, and count examples that survive its single-token preference filtering. Keep the reference fixed; monitor repetition and general capability.
Memory Budget a reference and vocabulary comparisons. Long-context mode is not wired; shorten inputs without losing the task signal.
GRPO
Inspect sampled completions and ensure rewards vary within each prompt group. Keep at least two completions; watch reward, KL, clipping, and truncation rates.
Memory Rollout storage grows with group size and completion length. Lower batch and completion cap first; a reference is loaded even when beta is zero.
KLPO
Use a positive beta and nonconstant rewards. Start with token-level Monte Carlo KL, then compare estimator variance, reward, and KL on fixed prompts; estimator changes affect the objective.
Memory Full KL stores full-vocabulary behavior distributions. Other estimators reduce stored auxiliaries, but current-policy logits still cost memory.
Online DPO
Calibrate the pairwise judge on clear, ambiguous, and reversed pairs. Compare with a fixed prompt pool, reference, and judge; inspect generated pairs and held-out capability.
Memory Budget policy, reference, judge, and rollouts. Shorten completions and use the supported scoring microbatch setting.
XPO
Compare against Online DPO with the same prompts and judge. Supply a nonempty alpha list no longer than the iteration budget; these values are exploration weights, not learning rates.
Memory Three model roles plus paired rollouts can be resident. Keep rollouts short and batches small; exploration may increase completion lengths.
PPO
Freeze the reference for comparisons, test judge consistency, and set PPO’s clip epsilon explicitly. Monitor KL, clipping, judge agreement, and held-out generations.
Memory Budget paired generation and reference/judge residency. Scoring microbatches help backward peaks but do not remove model copies or rollout caches.
RLHF REINFORCE
Calibrate the scalar reward on clearly good, bad, and ambiguous completions. Use diverse prompts and inspect reward, KL, and general capability for reward hacking.
Memory Budget policy, reference, judge, and generated completions. Shorten rollouts and batch size; microbatching does not remove model residency.
Agent control.
Local runs.
The MCP server validates and manages training jobs on your Mac. The skill helps an agent choose the right mode, follow its data contract, and use the server tools correctly.
One skill, seven tools
Discover modes, validate the proposed configuration, start a run, and monitor or stop it by run ID. Runs, logs, and checkpoints are stored locally and survive an MCP server restart. One run trains at a time per runs directory.
list_training_modescheck_training_configstart_trainingtraining_statustraining_loglist_training_runsstop_trainingTraining stays on the Mac; model and dataset Hub IDs may need to be downloaded first. The server has no tenant isolation. MCP defaults to stdio; local HTTP is available for clients that need it.
pip install -U "mlx-lm-lora[mcp]"
# stdio (default)
mlx-lm-lora-mcp
# local Streamable HTTP
mlx-lm-lora-mcp --transport http --port 8765Use the discovered schema
Pass settings as flat tool arguments. Put trainer-specific options in extra_config as a JSON-encoded string. Validate first, then save the returned run ID and use it for status and logs.
{
"model": "tiny-random/qwen3",
"data": "mlx-community/wikisql",
"train_mode": "sft",
"train_type": "lora",
"iters": 3,
"batch_size": 1,
"max_seq_length": 128,
"extra_config": "{\"steps_per_report\": 1}"
}The MCP skill and API contract evolve together. Browse the skill and per-mode references ↗ · Read server setup and configuration ↗
Spend memory
on the signal.
Apple silicon shares one memory pool across model weights, activations, optimizer state, generated tokens, and any reference or judge models. Tune the part that is actually peaking.
1 · Shrink the working set
Start with LoRA, batch size 1, and only the context the task needs. Lower adapter rank or trainable layers when appropriate. Preserve complete preference pairs and supervised targets.
2 · Load efficiently
Prefer a compatible pre-quantized model if weight loading is the limit. On-the-fly quantization loads source weights first; it can peak before the smaller quantized copy exists.
3 · Trade compute for activations
Gradient checkpointing recomputes activations. Lower physical batch to reduce its peak, then use accumulation to recover an effective batch. Accumulation alone does not shrink a minibatch.
4 · Bound generation
For online methods, reduce completion length and prompt batch; prompt length alone does not cap generated KV caches. Score in microbatches where the mode supports it.
5 · Count every model
Preference and online methods may load reference or judge models in addition to the policy. Policy quantization does not quantize those extra models; check each method’s memory note.
6 · Leave room to export
Keep fusion off during pilots. Save adapters and plan export separately: merging or dequantizing weights can create another memory peak.
| Control | Where it is wired | Practical implication |
|---|---|---|
| Sequential long-context chunks | SFT, DPO, CPO, ORPO | Fixed 512-token chunks; compare quality because gradient flow can differ. |
| Configurable scoring microbatch | Online DPO, XPO, PPO, RLHF REINFORCE | Helps scoring/backprop; does not bound generation or unload extra models. |
| GRPO / KLPO scoring | Internal microbatching | The configurable microbatch field is not forwarded; rollout/distribution storage still matters. |
| Gradient checkpointing / accumulation | All 12 modes | Checkpointing trades compute for activations; accumulation does not lower physical-batch peaks. |
| Quantization-aware training | SFT, DPO, ORPO, DSLA | QAT is a training feature, not a low-memory model-loading switch. |
For method-specific caveats, model residency, and a tuning order, read the full memory guide ↗.
First run
From zero
to adapter.
Install the toolkit, point it at a compatible model and dataset, then keep the whole loop on your machine.
View document ↓# install the toolkit
pip install mlx-lm-lora
# train a LoRA adapter
mlx_lm_lora train
--model mlx-community/Llama-3.2-3B-Instruct-4bit
--data ./data
--iters 600
# install the studio
Open the MLX-LoRA-Studio GitHub repo
Download the .dmg and install it
Two ways in