backpropagate 1.5.0

Production-ready headless LLM fine-tuning with smart defaults, Windows support, and modular architecture

日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

Train an adapter. Ship it to Ollama. Move on.

Backpropagate is a Python library for fine-tuning large language models on a single GPU. Three lines of code train a 7B model on a 16GB card. One more command exports it to Ollama so you can ollama run your finetune. Works first-class on Windows.

from backpropagate import Trainer

trainer = Trainer("Qwen/Qwen2.5-7B-Instruct")
trainer.train("my_data.jsonl", steps=100)
trainer.export("gguf", quantization="q4_k_m")

backprop export ./output/lora --format gguf --quantization q4_k_m --ollama --ollama-name my-model
ollama run my-model

That's it. There's no YAML config file. There's no accelerate launch ceremony. There's no separate "now convert it to GGUF" tutorial. If you have a CUDA GPU and a JSONL file with your training data, you're three lines away from a working finetune.

Install

# Recommended: isolated Python install (no conflicts with system Python or other projects)
pipx install backpropagate

# Or via uv (faster install, same isolation)
uv tool install backpropagate

# Standard pip (if you manage your own virtualenv)
pip install backpropagate

If you want the optional features, swap the install for one of these:

pipx install "backpropagate[standard]"   # adds Unsloth (2x faster training) + the web UI
pipx install "backpropagate[full]"       # adds everything: unsloth, ui, monitoring, export, etc.

Prefer Docker? docker pull ghcr.io/mcp-tool-shop-org/backpropagate:latest works too. Images ship for both linux/amd64 and linux/arm64, so Apple Silicon and ARM Linux operators get a native image. A canonical compose.yaml for "UI in a container" lives at the repo root — docker compose up brings the web UI up on http://localhost:7860 with a persistent ~/.backpropagate volume mount.

Where Backpropagate sits in the space

There are several good libraries for fine-tuning LLMs. They're each great at different things:

• Axolotl — if you like YAML configs and want a community of recipes to copy from
• LLaMA-Factory — if you want DPO/PPO/RLHF and a web GUI
• Unsloth — if you need the fastest possible training and you're on a supported model family
• torchtune — if you want Meta's first-party PyTorch-native recipes you can edit

Backpropagate is the missing option: a 3-line Python API for solo operators on a single consumer GPU who want to train an adapter and ship it. No YAML, no GUI, no online RL (PPO/GRPO), no multi-node. Just the loop everyone actually needs and the export step that gets in the way.

If you tried one of the libraries above and bounced off the config-file ceremony, or hit a model-family gap, or wanted Windows-first defaults — Backpropagate is for you.

What you can fine-tune on a 16GB consumer GPU

Here's the practical envelope on a 16GB card (RTX 4080 / 5080 / 4070 Ti Super):

Model	Method	Status
Qwen-3.5-4B / Phi-4-mini-3.8B / SmolLM3-3B	LoRA / QLoRA / DoRA	Comfortable. Full sequence length, room to spare.
SmolLM3-3B / Qwen2.5-3B / Llama-3.2-3B / Llama-3.2-1B	mode="full" (full fine-tuning)	v1.4 — pass --mode=full on backprop train or Trainer(..., mode="full"). Loads full-precision (bf16) weights — no 4-bit, no adapter; gradient checkpointing + paged 8-bit Adam keep the footprint inside 16GB.
Qwen-2.5-7B / Llama-3.1-8B / Mistral-7B	QLoRA	Standard. ~7-8 GB. Backpropagate's default presets.
Llama-3 13B	QLoRA + sample packing	Tight but works. Use shorter sequences.
Mixtral 8x7B (47B total parameters)	—	Out of scope — 2-bit (AQLM / QuIP#) breaks the mergeable-adapter + GGUF-export contract, so it was retired in the v1.5 trajectory brief. On a 16GB card, use a ≤8B base.

mode="full" admits models up to 4B parameters. The four presets in the full-FT row above are genuine ~3B (true parameter count 3.08–3.24B) and fit a 16GB card. The 3.8–4B class (Phi-4-mini-3.8B, Qwen-3.5-4B) is also accepted by the ceiling but needs a 24GB+ card for full FT — weights + gradients alone approach 16GB before the optimizer and activations — so on a 16GB card use mode="lora" for those (they're in the LoRA row). Models >4B exit with RUNTIME_FULL_FT_MODEL_TOO_LARGE.

2-bit quantization (AQLM / QuIP#) is out of scope. It was scoped for v1.4, then retired in the v1.5 trajectory brief: a 2-bit base can't be cleanly merged back into full-precision weights, which breaks Backpropagate's mergeable-adapter → GGUF → Ollama export contract (the whole point of the pipeline). The headroom levers Backpropagate ships instead are the v1.5 FP8 compute path (--fp8, Blackwell/Hopper) and mode="full" for ≤4B models — both stay mergeable and exportable.

For models 3B and smaller, full fine-tuning (not just LoRA) is feasible on 16GB and now ships in v1.4 as mode="full". Pass Trainer(..., mode="full") or backprop train --mode=full --model phi-4-mini-3.8b to enable it. A hard gate refuses the mode for models > 4B with RUNTIME_FULL_FT_MODEL_TOO_LARGE, naming LoRA + the sub-4B presets as the recovery options. See the full fine-tuning handbook page for the configuration math + Biderman 2024 / Thinking Machines 2025 quality comparison. For 7B+ models, full fine-tuning needs a 24GB+ GPU — consider an A100 cloud rental, or stick with LoRA, which recent research shows matches full fine-tuning quality on most post-training tasks anyway (see the anti-pitch section for citations).

What Backpropagate is NOT for

If your use case is below, you'll have a better time with a different library — Backpropagate is not the right pick and trying to make it work would cost more than just reaching for the right tool. Reading this section before you start saves the install-and-bounce cycle:

• Full-parameter fine-tuning of 7B+ models — Backpropagate uses LoRA / QLoRA, which trains a small adapter rather than updating every weight. For models 7B and larger, full fine-tuning needs 24GB+ of GPU memory and doesn't fit on a 16GB consumer card. For models 3B and smaller, full fine-tuning IS feasible on 16GB and ships in v1.4 as mode="full" (pass Trainer(..., mode="full") or --mode=full on the CLI; a hard gate raises RUNTIME_FULL_FT_MODEL_TOO_LARGE for models > 4B and names LoRA + the sub-4B presets as recoveries). The bigger picture: recent research (Biderman 2024, Thinking Machines 2025) shows that LoRA at correct configuration matches full fine-tuning quality on most post-training tasks (instruction-following, domain adaptation, persona/style) at 67% of the compute — so for the work most operators actually want, you don't lose anything by sticking with LoRA. mode="full" exists for the cases where you've measured a quality gap and decided to spend the extra compute. If you genuinely need full fine-tuning of a 7B+ model, use HuggingFace transformers.Trainer directly on a 24GB+ card.
• Online RL — PPO / GRPO / RLVR — Backpropagate does single-stage SFT plus reference-free preference tuning (ORPO ships in v1.5; SimPO/KTO are planned). What it does not do is online reinforcement learning — PPO, GRPO, or RLVR — which needs a reward model or a generation-and-scoring loop on top of the training step. For those, use TRL directly or LLaMA-Factory. (Reference-free preference tuning fits the single-stage envelope because there's no separate reference model to hold in memory; see the ORPO note under Quick Start.)
• Multi-node training — single GPU on one machine only. Multi-GPU on one machine works (via accelerate launch) but isn't officially supported.
• macOS training on the CUDA rail — Apple Silicon doesn't have CUDA, so the CUDA path has to run on a Linux or Windows box with an NVIDIA GPU. You can still run the trained model on a Mac via Ollama. New in v1.5: an experimental MLX rail (--backend mlx) trains a LoRA adapter natively on Apple Silicon — see Apple Silicon (MLX). It is LoRA-SFT-only and built-but-not-yet-dogfood-verified on real silicon, so for anything beyond a LoRA SFT (ORPO, full fine-tune, FP8, multi-run) you still want the CUDA rail.
• Anything outside the tested model families — Qwen 2.5 / 3.5 (7B / 4B), Phi-4-mini-3.8B, SmolLM3-3B, Llama 3.2 (3B / 1B), Mistral 7B. Other models often work but aren't pinned in CI.

If you need any of those things, reach for one of the libraries listed above. They're better at them.

What Backpropagate gives you

Four things, in one install:

1. A real 3-line API that runs without a config file. The snippet at the top of this README runs end-to-end. No accelerate config, no YAML, no Hydra overrides. Just Trainer(model).train(data) and you have a finetune.

2. Windows that actually works. Most ML libraries treat Windows like an afterthought. Backpropagate is tested first-class on Windows + RTX 5080. The library handles the runtime quirks for you — it knows how to pre-tokenize your data so Windows multiprocessing doesn't crash, it automatically disables xformers on RTX 40/50 cards where it would break, and it picks dataloader settings that don't blow up. You don't have to know any of this. It just runs.

3. Built for unattended runs. Training takes hours. You don't want to babysit it. Backpropagate is designed to be left running:

• If you run out of GPU memory, it automatically halves the batch size and retries — up to three times. No hand-tuning.
• If your GPU gets too hot, it pauses until things cool down and then continues.
• Every checkpoint is written atomically — if your laptop crashes mid-save, the previous good checkpoint is still intact.
• Every training run gets a unique ID that's stamped onto every log line, every checkpoint, and every Weights & Biases entry. If something goes wrong, one ID lets a maintainer correlate everything.
• Errors come with stable codes (RUNTIME_GPU_OOM, DEP_OLLAMA_REGISTRATION_FAILED, etc.) so you can grep your logs and the troubleshooting guide for the fix. CUDA-specific failures have a dedicated CUDA troubleshooting page.

4. One command from trained adapter to ollama run. Lots of libraries train a model. Few of them get out of your way when you want to actually use it. Backpropagate exports to GGUF (the format Ollama uses) and registers an Ollama model in one command. You go from "training done" to "I can chat with my finetune" in about 30 seconds.

Quick Start

The repo ships a tiny example dataset so the snippet from the top of this README runs on a clean install:

pipx install "backpropagate[standard]"

python -c "
from backpropagate import Trainer
trainer = Trainer('Qwen/Qwen2.5-7B-Instruct')
trainer.train('examples/quickstart.jsonl', steps=10)
trainer.export('gguf', quantization='q4_k_m')
"

This trains a Qwen 2.5 7B adapter on 5 short ShareGPT-format conversations, then exports the result to GGUF. For your own data, format your JSONL one example per line:

{"conversations": [{"from": "human", "value": "What is Python?"}, {"from": "gpt", "value": "A programming language."}]}
{"conversations": [{"from": "human", "value": "Explain recursion."}, {"from": "gpt", "value": "A function that calls itself."}]}

Alpaca (instruction / output), OpenAI chat (messages), and raw text formats also work — Backpropagate auto-detects the format.

Preference tuning (ORPO)

New in v1.5: train on preferences instead of plain demonstrations. ORPO is reference-free and single-stage — it folds the preference signal into the SFT step, so there's no separate reward or reference model and the 3-line shape is unchanged. Pass --method orpo (CLI) or method="orpo" (Python) and feed it a dataset of {prompt, chosen, rejected} (or just {chosen, rejected}) rows:

{"prompt": "What is Python?", "chosen": "A high-level programming language known for readability.", "rejected": "idk look it up"}
{"prompt": "Explain recursion.", "chosen": "A function that calls itself with a smaller input until a base case.", "rejected": "when something repeats"}

from backpropagate import Trainer

trainer = Trainer("Qwen/Qwen2.5-7B-Instruct", method="orpo")
trainer.train("preferences.jsonl", steps=100)
trainer.export("gguf", quantization="q4_k_m")

backprop train --data preferences.jsonl --method orpo --steps 100

The default learning rate auto-lowers to 8e-6 for ORPO (the loss is sharper than plain SFT); tune --orpo-beta (default 0.1) to weight the odds-ratio penalty. In v1.5 ORPO is mode="lora" only. SimPO and KTO are planned follow-ons; for online RL (PPO/GRPO) see What Backpropagate is NOT for.

Reasoning-trace SFT (R1 distillation)

New in v1.5: distill a reasoning model the easy way. Pass --reasoning-trace (CLI) or Trainer(..., reasoning_trace=True) (Python) and feed it traces that keep a <think>...</think> chain-of-thought inside the assistant turn — the pure-SFT half of DeepSeek-R1 distillation, no RL required. Backpropagate keeps <think> in the training target, drops empty / over-long traces (trace-length filtering), and raises the default max_seq_length to 8192 for the longer CoT. Critically, <think> stays plain text — no special tokens, no embedding resize — so the merged GGUF still exports to Ollama like any other fine-tune. SFT only. See the reasoning-trace recipe for the dataset shape and the tunable token band.

Apple Silicon (MLX) — experimental, v1.5

New in v1.5: one API, two rails. CUDA stays the canonical, verified backend; MLX is a second rail that trains on an M-series Mac via Apple's mlx_lm.lora toolchain (unified memory, no CUDA). The same 3-line shape picks the rail by hardware — backend='auto' (the default) routes to CUDA on NVIDIA and to MLX on Apple Silicon, so existing CUDA rigs are byte-identical:

from backpropagate import Trainer

# On an M-series Mac with `pip install 'backpropagate[mlx]'`:
trainer = Trainer("mlx-community/Qwen2.5-0.5B-Instruct-4bit", backend="mlx")
trainer.train("examples/quickstart.jsonl", steps=100)

backprop train --data my_data.jsonl --backend mlx --steps 100

In v1.5 the MLX rail is LoRA SFT only — no ORPO, no FP8, no mode='full', no multi-run on MLX yet (each is rejected with CONFIG_INVALID_SETTING; use backend='cuda'/'auto' on an NVIDIA box for those). The resulting adapter is plain safetensors and exports to Ollama through the same path as the CUDA rail.

⚠️ Honest status: the MLX rail ships in v1.5 built + unit-tested (mocked) but NOT yet dogfood-verified on real Apple Silicon — mlx-lm is Apple-only and could not be run on the NVIDIA rig this was authored on. Treat it as experimental (same framing as the FP8 path), and please report anomalies once it runs on an M-series Mac. Forcing --backend mlx on a non-Apple host errors with CONFIG_INVALID_SETTING; a missing mlx_lm toolchain on a Mac raises DEP_MLX_UNAVAILABLE.

For more end-to-end workflows (fine-tune-and-push-to-HF-Hub, resume after OOM, multi-run SLAO across a long campaign, etc.) see the handbook recipes page.

Web UI (optional)

If you'd rather click than type Python, install the UI extra and launch:

pipx install "backpropagate[ui]"
backprop ui --port 7862

A local web interface opens at http://localhost:7862 for browsing datasets, validating formats, and assembling a training config visually. Training itself runs via backprop train (UI-driven training is on the roadmap — the Start button currently surfaces that note). The UI is local-only by default. To expose it to other devices, see Web UI below for the --share + --auth security contract.

Multi-run training

If you want to fine-tune incrementally across multiple datasets — say you get new training data every week and want to add it without forgetting what you learned before — Backpropagate's multi_run mode is for you:

from backpropagate import Trainer

trainer = Trainer("Qwen/Qwen2.5-7B-Instruct")

result = trainer.multi_run(
    dataset="HuggingFaceH4/ultrachat_200k",
    num_runs=5,
    steps_per_run=100,
    samples_per_run=1000,
)

This runs five training passes, merging the adapter between runs in a way that preserves earlier knowledge while incorporating new examples. The technique is based on recent continual-learning research — see References at the bottom of this README.

The CLI version:

backprop multi-run --data my_data.jsonl --runs 5 --steps 100 --samples 1000

Resume from checkpoint

A 5-run training that crashes at run 4 is recoverable. Every multi-run session writes its run ID into the on-disk history and checkpoint manifest, so picking up where you left off is one command:

backprop resume <run-id>
backprop multi-run --data ... --resume <run-id>
backprop train --data ... --resume <run-id>     # single-run resume

The default behavior of backprop multi-run (no --resume) auto-detects an in-progress entry in the same output directory and continues it. To force a clean start, point at a fresh output directory.

Training history

Every backprop train and backprop multi-run invocation records a row in <output>/run_history.json — model used, dataset, hyperparameters, status, final loss, loss history. You can list and inspect past runs:

backprop list-runs                         # last 20 runs
backprop list-runs --status failed         # filter by status
backprop list-runs --json --limit 100      # machine-readable
backprop show-run abcd1234                 # detail view (partial ID is fine)

Experiment tracking

Backpropagate auto-detects installed experiment trackers (Weights & Biases, TensorBoard, MLflow) and wires them in. If wandb is installed and you're logged in, every run automatically logs to W&B with a run name that matches the on-disk run ID — so you can grep across W&B, your logs, and run_history.json using one identifier.

pip install backpropagate[monitoring]   # installs wandb + psutil
wandb login                             # one-time setup
backprop train --data my_data.jsonl

Override with Trainer(report_to=["wandb"]), Trainer(report_to=["tensorboard"]), or Trainer(report_to="none") to opt out.

Web UI

The Reflex web interface is opt-in — install with pipx install "backpropagate[ui]" and launch:

backprop ui --port 7862

The UI runs locally on http://localhost:7862. Today it covers the browse / validate / configure half of the workflow — point it at a dataset, check the auto-detected format and stats, pick a model, and assemble a run config. Launching the run is done from the CLI (backprop train / backprop multi-run); the in-UI Start button surfaces a note pointing there. UI-driven training is a planned follow-up — until then the UI is the on-ramp and the CLI is the trigger.

To expose it to other devices (other people on your network, a public URL, etc.) you must pair --share (or --host) with --auth:

backprop ui --share --auth alice:hunter2

backprop ui --share without --auth exits with an error. The reason: --share publishes a URL anyone on the internet can reach, and without authentication that means anyone can drive your training pipeline and read your HuggingFace token. There is no opt-out for this — if you don't want to set credentials, use SSH port-forwarding instead:

# On the client:
ssh -L 7860:localhost:7860 <your-training-host>
# On the server:
backprop ui                             # no --share
# Then open http://localhost:7860 in your local browser

See handbook/security.md for the full threat model.

Filesystem writes from the UI are sandboxed to a single directory:

• Default: ~/.backpropagate/ui-outputs
• Override: set BACKPROPAGATE_UI__OUTPUT_DIR=/path/you/own
• The override is denylist-validated — system or credential paths (/etc, ~/.ssh, ~/.aws, C:\Windows\System32, etc.) are refused

Platform notes

Requirements: Python 3.10+ · CUDA GPU (8GB+ VRAM) · PyTorch 2.0+

Python 3.10 reaches upstream end-of-life in October 2026 and is scheduled for drop in v1.5. For new installs, prefer Python 3.11 or 3.12 — 3.11 is the most-tested floor.

Backpropagate handles the runtime quirks of training on different platforms, but it can't fix install-time problems. The two most common are:

• Wrong CUDA wheel. PyTorch is published one binary per CUDA version. If you pick the wrong one, you silently get CPU-only PyTorch and training is impossibly slow. Use the wheel picker at https://pytorch.org/get-started/locally/ for your driver. Run nvidia-smi to see your driver / CUDA version.
• Windows + GGUF export. The [export] extra builds llama-cpp-python from source, which needs Visual Studio Build Tools (C++ component) and CMake.

macOS: the CUDA rail is not supported (no CUDA) — a CUDA-routed trainer.train() raises DEP_GPU_NOT_AVAILABLE, and you can run the trained adapter on a Mac via Ollama. New in v1.5: an experimental MLX rail (--backend mlx, pip install 'backpropagate[mlx]') trains a LoRA adapter natively on Apple Silicon via mlx_lm.lora — LoRA SFT only, and built + unit-tested but not yet dogfood-verified on real silicon (see Apple Silicon (MLX)). For the CUDA path, or for ORPO / full fine-tune / FP8 / multi-run, use a CUDA Linux or Windows machine.

See the troubleshooting handbook page for the long-form install fix-it guide, and the dedicated CUDA troubleshooting page for driver / VRAM / xformers / bf16-vs-fp16 issues.

CLI

Every Python API has a CLI mirror:

backprop train --data my_data.jsonl --model Qwen/Qwen2.5-7B-Instruct --steps 100
backprop multi-run --data my_data.jsonl --runs 5 --steps 100
backprop export ./output/lora --format gguf --quantization q4_k_m --ollama --ollama-name my-model
backprop ui --port 7862
backprop info                          # environment + version snapshot
backprop list-runs                     # past training runs
backprop show-run <run-id>             # detail view
backprop resume <run-id>               # resume a crashed run
backprop push ./output/lora --repo me/my-model    # push adapter to HuggingFace Hub
backprop diff-runs <run-a> <run-b>     # diff two runs side by side
backprop replay <run-id>               # re-run with same config / dataset
backprop export-runs --format jsonl    # bulk export run history

Full reference at the CLI handbook page, or backprop <subcommand> --help.

Configuration

Every setting can be overridden with an environment variable using the BACKPROPAGATE_ prefix:

Variable	Default	Notes
BACKPROPAGATE_LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR
BACKPROPAGATE_LOG_JSON	auto	Force JSON or console logs
BACKPROPAGATE_MODEL__NAME	Qwen/Qwen2.5-7B-Instruct	Default model
BACKPROPAGATE_TRAINING__LEARNING_RATE	2e-4	Learning rate
BACKPROPAGATE_LORA__R	256	LoRA rank (v1.3 default; pass --lora-preset=fast for the v1.2.x default of 16)
BACKPROPAGATE_UI__OUTPUT_DIR	~/.backpropagate/ui-outputs	UI filesystem sandbox

Nested keys use double underscore (MODEL__NAME, not MODEL_NAME). The full reference is at the env-vars handbook page.

Model presets

Preset	VRAM	License	Notes
Qwen-3.5-4B	~8GB	Apache 2.0	Recommended default for sub-5B. Best quality at this size.
Phi-4-mini-3.8B	~8GB	MIT	Strong on reasoning / math / code. Strict license-clean.
SmolLM3-3B	~6GB	Apache 2.0	Fully open recipe. Native 64K context.
Qwen 2.5 7B	~12GB	Apache 2.0	Existing default. Best quality of the legacy 7B presets.
Qwen 2.5 3B	~8GB	Qwen-Research	⚠ research license — see Qwen license terms before commercial use.
Llama 3.2 3B	~8GB	Llama Community	Solid alternative to Qwen 3B with permissive caveats.
Llama 3.2 1B	~6GB	Llama Community	For quick experiments on small cards.
Mistral 7B	~12GB	Apache 2.0	Comparable to Qwen 7B, different chat template.

Other models often work, but only these eight are pinned in CI. Pass --lora-preset=quality (default) for rank-256 / all-linear targets per Biderman 2024 + Thinking Machines 2025, or --lora-preset=fast for the legacy rank-16 / q+v target if you need the v1.2.x footprint.

Troubleshooting

A short index of the most common first-run failures. The full reverse index is at the troubleshooting handbook page. For driver / VRAM / mixed-precision deep-dive see the CUDA troubleshooting page.

Symptom	Error code	Fix
GPU runs out of memory mid-training	RUNTIME_GPU_OOM	Automatic — Backpropagate halves the batch size and retries up to 3 times. To opt out: Trainer(oom_recovery=False). To force smaller: --batch-size 1.
HuggingFace returns 401 / "model not found"	DEP_MODEL_LOAD_FAILED	huggingface-cli login and retry. For typos, copy the exact ID from https://huggingface.co/models.
register_with_ollama connection refused	DEP_OLLAMA_REGISTRATION_FAILED	Start the daemon: ollama serve. Install from https://ollama.com. Retryable.
Disk full during checkpoint save	STATE_CHECKPOINT_INVALID	Atomic writes leave a .partial directory on crash — safe to delete. The previous good checkpoint is intact.
Training paused on GPU overheat	RUNTIME_GPU_TEMPERATURE_CRITICAL	Automatic — Backpropagate pauses on the temperature threshold and resumes as the GPU cools. Improve airflow if it keeps happening.
backprop ui --share rejected	RUNTIME_UI_AUTH_NOT_ENFORCED	Pass --auth user:password, or use SSH port-forwarding instead (see Web UI).
GGUF export failed on first try	RUNTIME_GGUF_EXPORT_FAILED	pip install backpropagate[export]; on Windows you also need Visual C++ Build Tools + CMake.

Reporting bugs

When something fails, Backpropagate prints a line at startup like run_started run_id=<uuid> and binds the same ID to every log line, every checkpoint, and every Weights & Biases entry. Include the run_id in any bug report — it lets a maintainer correlate everything for that exact run.

A good bug report includes:

1. The run_id — the UUID printed at startup. One UUID lets a maintainer correlate every log line, every checkpoint, and every Weights & Biases entry for that exact run.
2. The error code — the [CODE_NAME]: message line in stderr. See error codes for the catalog of stable codes.
3. The redacted traceback. Stderr is automatically redacted in non-verbose mode (Bearer tokens, sk-*, hf_*, AWS keys, password= / token= / api_key= pairs are scrubbed) — safe to paste. For the full unredacted traceback, re-run with BACKPROPAGATE_DEBUG=1 (or --verbose); review before posting.
4. The backprop info output. One command prints Python / PyTorch / CUDA / GPU model / VRAM / OS / installed extras — everything the maintainer needs to bisect a platform-specific regression.

The bug report template prompts for each of these explicitly so triage moves fast. Questions, ideas, or "is this expected?" threads belong in GitHub Discussions. Security issues should be reported privately via the GitHub Security Advisory form — see SECURITY.md for the policy and response timelines.

Privacy

All training happens locally on your GPU. Backpropagate makes no network requests except to download models from HuggingFace (which you initiate). No telemetry, no cloud dependency.

References

Backpropagate's defaults and multi-run training mode are built on recent research. If you're interested in the underlying techniques:

• Hu et al. 2021. LoRA: Low-Rank Adaptation of Large Language Models. arXiv:2106.09685 — the foundational paper introducing LoRA, which is how Backpropagate trains adapters efficiently.
• Biderman et al. 2024. LoRA Learns Less and Forgets Less. arXiv:2405.09673 — empirical evidence that LoRA at rank 256 with all-linear targets matches full fine-tuning quality on most post-training tasks at 67% of the compute. Drives Backpropagate's v1.3 default LoRA configuration.
• Thinking Machines 2025. LoRA Without Regret. thinkingmachines.ai/blog/lora — the practical follow-up identifying the 10× learning-rate-vs-full-FT correction needed at high LoRA rank.
• Kirkpatrick et al. 2017. Overcoming catastrophic forgetting in neural networks. arXiv:1612.00796 — the original characterization of why neural networks "forget" earlier training when you fine-tune on new data (EWC — Elastic Weight Consolidation).
• Wang et al. 2023. Orthogonal Subspace Learning for Language Model Continual Learning. arXiv:2310.14152 — O-LoRA, an earlier approach to using LoRA for continual learning by constraining new adapters to orthogonal subspaces.
• Yadav et al. 2023. TIES-Merging: Resolving Interference When Merging Models. arXiv:2306.01708 — a foundational technique for merging multiple fine-tuned models without interference.
• Qiao & Mahdavi 2025. Merge before Forget: A Single LoRA Continual Learning via Continual Merging. arXiv:2512.23017 — the specific algorithm Backpropagate's multi-run merger implements. A December 2025 preprint; Backpropagate is the paper's first known downstream adopter.

License

MIT — see LICENSE.

---

Built by MCP Tool Shop