peft

library0.18.1pypypi✓ verified 50d ago

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.

ai-ml llm-agents

pip install peft

github ↗package ↗homepage ↗

Install & Compatibility

Where this runs

tested against v0.19.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

8/10 runs

py 3.11

✕ build_error

8/10 runs

py 3.12

✕ build_error

8/10 runs

py 3.13

✕ build_error

8/10 runs

py 3.9

✕ build_error

✕ timeout

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LoraConfig

✓ from peft import LoraConfig

✗ from peft import LoraConfig

get_peft_model

✓ from peft import get_peft_model

✗ from peft import get_peft_model

TaskType

✓ from peft import TaskType

✗ from peft import TaskType

LoRA fine-tuning on all linear layers. Save adapter only — not the full model.

from transformers import AutoModelForCausalLM, AutoTokenizer from peft import LoraConfig, get_peft_model, TaskType, prepare_model_for_kbit_training import torch # Load base model model = AutoModelForCausalLM.from_pretrained( 'meta-llama/Llama-3.2-1B', torch_dtype=torch.bfloat16, device_map='auto' ) # Configure LoRA config = LoraConfig( r=16, lora_alpha=32, target_modules='all-linear', # applies to all linear layers (QLoRA style) lora_dropout=0.05, bias='none', task_type=TaskType.CAUSAL_LM ) model = get_peft_model(model, config) model.print_trainable_parameters() # trainable params: 6,815,744 || all params: 1,242,343,424 || trainable%: 0.55 # After training — save adapter only: model.save_pretrained('lora_adapter/') # Reload for inference: base = AutoModelForCausalLM.from_pretrained('meta-llama/Llama-3.2-1B', torch_dtype=torch.bfloat16) from peft import PeftModel peft_model = PeftModel.from_pretrained(base, 'lora_adapter/')

Debug

Known issues

breakingPEFT <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.

fix

Upgrade to peft>=0.18.0 before upgrading to Transformers v5.

affects: < 0.18.0

breakingPython 3.9 support dropped in PEFT 0.18.0.

fix

Pin peft<0.18.0 for Python 3.9 environments, or upgrade Python to 3.10+.

affects: >= 0.18.0

breakingmerge_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.

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.

affects: all

breakingprepare_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.

fix

Pattern: model = prepare_model_for_kbit_training(model) then model = get_peft_model(model, config). Enable gradient checkpointing first: model.gradient_checkpointing_enable().

affects: all

gotchasave_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.

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().

affects: all

gotchatarget_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'.

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)}.

affects: all

breakingpip 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.

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.

affects: all

Upgrade

Version history

0.19.1latest on PyPI

Audit

Dependencies

transformersrequiredRequired. Not pinned — must be compatible version. PEFT <0.18.0 incompatible with Transformers v5.

acceleraterequiredRequired. Installed automatically.

bitsandbytesoptionalRequired for QLoRA (4-bit/8-bit quantization). Not installed automatically.

Agent activity

18 hits · last 30 days

oai-searchbot