{"id":215,"library":"peft","title":"PEFT","description":"Hugging Face Parameter-Efficient Fine-Tuning library. LoRA, QLoRA, LoHa, IA3, prompt tuning and more. Current version is 0.18.1 (Jan 2026). Requires Python >=3.10. PEFT <0.18.0 is incompatible with Transformers v5.","status":"active","version":"0.18.1","language":"python","source_language":"en","source_url":"https://github.com/huggingface/peft/releases","tags":["fine-tuning","lora","qlora","huggingface","llm","adapters","parameter-efficient"],"install":[{"cmd":"pip install peft","lang":"bash","label":"Standard"},{"cmd":"pip install peft bitsandbytes","lang":"bash","label":"With QLoRA (4-bit/8-bit quantization)"}],"dependencies":[{"reason":"Required. Not pinned — must be compatible version. PEFT <0.18.0 incompatible with Transformers v5.","package":"transformers","optional":false},{"reason":"Required. Installed automatically.","package":"accelerate","optional":false},{"reason":"Required for QLoRA (4-bit/8-bit quantization). Not installed automatically.","package":"bitsandbytes","optional":true}],"imports":[{"wrong":"from peft import LoraConfig","symbol":"LoraConfig","correct":"from peft import LoraConfig"},{"wrong":"from peft import get_peft_model","symbol":"get_peft_model","correct":"from peft import get_peft_model"},{"wrong":"from peft import TaskType","symbol":"TaskType","correct":"from peft import TaskType"}],"quickstart":{"code":"from transformers import AutoModelForCausalLM, AutoTokenizer\nfrom peft import LoraConfig, get_peft_model, TaskType, prepare_model_for_kbit_training\nimport torch\n\n# Load base model\nmodel = AutoModelForCausalLM.from_pretrained(\n    'meta-llama/Llama-3.2-1B',\n    torch_dtype=torch.bfloat16,\n    device_map='auto'\n)\n\n# Configure LoRA\nconfig = LoraConfig(\n    r=16,\n    lora_alpha=32,\n    target_modules='all-linear',  # applies to all linear layers (QLoRA style)\n    lora_dropout=0.05,\n    bias='none',\n    task_type=TaskType.CAUSAL_LM\n)\n\nmodel = get_peft_model(model, config)\nmodel.print_trainable_parameters()\n# trainable params: 6,815,744 || all params: 1,242,343,424 || trainable%: 0.55\n\n# After training — save adapter only:\nmodel.save_pretrained('lora_adapter/')\n\n# Reload for inference:\nbase = AutoModelForCausalLM.from_pretrained('meta-llama/Llama-3.2-1B', torch_dtype=torch.bfloat16)\nfrom peft import PeftModel\npeft_model = PeftModel.from_pretrained(base, 'lora_adapter/')","lang":"python","description":"LoRA fine-tuning on all linear layers. Save adapter only — not the full model."},"warnings":[{"fix":"Upgrade to peft>=0.18.0 before upgrading to Transformers v5.","message":"PEFT <0.18.0 is incompatible with Transformers v5. Using peft<0.18.0 with transformers>=5.0 will raise ImportError or cause silent incorrect behavior.","severity":"breaking","affected_versions":"< 0.18.0"},{"fix":"Pin peft<0.18.0 for Python 3.9 environments, or upgrade Python to 3.10+.","message":"Python 3.9 support dropped in PEFT 0.18.0.","severity":"breaking","affected_versions":">= 0.18.0"},{"fix":"To merge and save a full-precision model: reload the base model without quantization (torch_dtype=torch.float16), then load the adapter and merge. Only quantize after merging if needed.","message":"merge_and_unload() produces incorrect results (different outputs than unmerged peft_model) when the base model is quantized (bitsandbytes 4-bit/8-bit). This is a fundamental limitation — quantized weights cannot be cleanly merged.","severity":"breaking","affected_versions":"all"},{"fix":"Pattern: model = prepare_model_for_kbit_training(model) then model = get_peft_model(model, config). Enable gradient checkpointing first: model.gradient_checkpointing_enable().","message":"prepare_model_for_kbit_training() must be called before get_peft_model() when using bitsandbytes quantization. Skipping it causes dtype mismatch errors during the backward pass.","severity":"breaking","affected_versions":"all"},{"fix":"To load: use PeftModel.from_pretrained(base_model, adapter_path). The base model must be loaded separately. To get a standalone model: use merge_and_unload() on a non-quantized base, then save_pretrained().","message":"save_pretrained() on a PeftModel saves only the adapter weights (small, ~MBs), not the full model. This is correct behavior but surprises users expecting a complete loadable checkpoint.","severity":"gotcha","affected_versions":"all"},{"fix":"Use target_modules='all-linear' to safely target all linear layers regardless of architecture name. Or inspect: {name for name, mod in model.named_modules() if isinstance(mod, torch.nn.Linear)}.","message":"target_modules must match the actual layer names of your model architecture. q_proj/v_proj is correct for LLaMA but wrong for GPT-2 (which uses c_attn). Use model.named_modules() to inspect, or set target_modules='all-linear'.","severity":"gotcha","affected_versions":"all"},{"fix":"Use a Python version and base image combination for which `torch` pre-built wheels are available (e.g., Python 3.8-3.11 on Debian/Ubuntu-based images). Alternatively, install `torch` manually from source, which can be complex.","message":"pip cannot find a compatible `torch` distribution for the current environment. This typically occurs on environments like Alpine Linux or with very recent Python versions (e.g., 3.13) for which `torch` does not provide pre-built wheels, causing `peft` installation to fail due to its `torch` dependency.","severity":"breaking","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.18.0':29 '0.18.1':22 '2026':24 '3.10':27 'adapt':42 'current':19 'effici':6,45 'face':3 'fine':8,36 'fine-tun':7,35 'hug':2 'huggingfac':40 'ia3':14 'incompat':31 'jan':23 'librari':10 'llm':41 'loha':13 'lora':11,38 'paramet':5,44 'parameter-effici':4,43 'peft':1,28 'prompt':15 'python':26 'qlora':12,39 'requir':25 'transform':33 'tune':9,16,37 'v5':34 'version':20","created_at":"2026-03-26T03:51:29.233206+00:00","updated_at":"2026-04-16T17:58:02.658473+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":0,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.19.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://huggingface.co/docs/peft","github":"https://github.com/huggingface/peft","docs":null,"changelog":null,"pypi":"https://pypi.org/project/peft/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","llm-agents"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":"stale"}}