@@ -4362,7 +4362,7 @@ magi = [{ name = "magi-attention", git = "https://github.com/SandAI-org/MagiAtte
 test = [
     { name = "coverage" },
     { name = "onnxruntime-gpu", marker = "platform_machine == 'x86_64' and sys_platform != 'darwin'", index = "https://aiinfra.pkgs.visualstudio.com/PublicPackages/_packaging/onnxruntime-cuda-13/pypi/simple/" },
-    { name = "peft", specifier = ">=0.18.1" },
+    { name = "peft", specifier = ">=0.19.1" },
     { name = "pytest" },
     { name = "pytest-shard" },
     { name = "ruamel-yaml" },
@@ -5286,7 +5286,7 @@ wheels = [
 
 [[package]]
 name = "peft"
-version = "0.18.1"
+version = "0.20.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "accelerate" },
@@ -5301,9 +5301,9 @@ dependencies = [
     { name = "tqdm" },
     { name = "transformers" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/d8/48/147b3ea999560b40a34fd78724c7777aa9d18409c2250bdcaf9c4f2db7fc/peft-0.18.1.tar.gz", hash = "sha256:2dd0d6bfce936d1850e48aaddbd250941c5c02fc8ef3237cd8fd5aac35e0bae2", size = 635030, upload-time = "2026-01-09T13:08:01.136Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b4/08/02541a2c29be7c78698f73d438bc0e733b214f3f35ec5db79fca8da8fc61/peft-0.20.0.tar.gz", hash = "sha256:4769c8093a4ca145fd6fb3fd4dd50449675f5fe46434ad1e98b285a132d4b1d0", size = 880503, upload-time = "2026-07-28T13:46:01.85Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/b3/14/b4e3f574acf349ae6f61f9c000a77f97a3b315b4bb6ad03791e79ae4a568/peft-0.18.1-py3-none-any.whl", hash = "sha256:0bf06847a3551e3019fc58c440cffc9a6b73e6e2962c95b52e224f77bbdb50f1", size = 556960, upload-time = "2026-01-09T13:07:55.865Z" },
+    { url = "https://files.pythonhosted.org/packages/28/79/13bcabb8048126422d5c4b880575d40886c726f354db88cfeed4325525bb/peft-0.20.0-py3-none-any.whl", hash = "sha256:0fbba16ffebfad3de96e06f2da6860fd860292324b85b6141909fa1e26ea9233", size = 775777, upload-time = "2026-07-28T13:45:59.809Z" },
 ]
 
 [[package]]
 
@@ -480,9 +480,11 @@ print(tokenizer.decode(output[0], skip_special_tokens=True))
 PEFT adapters must be loaded on top of the base model. Because the base NeMo AutoModel installation does not include the Hugging Face PEFT library, install a tested version in your active environment before running the inference code:
 
 ```bash
-uv pip install "peft>=0.18.1"
+uv pip install "peft>=0.19.1"
 ```
 
+LoRA adapters for models with fused MoE expert weights (for example Qwen3-MoE, MiniMax-M2, Nemotron 3) are exported in the ParamWrapper layout peft has used since 0.19.1, when peft changed it (huggingface/peft#3165); that is why the step above installs `peft>=0.19.1`. If such an adapter has to be loaded by a consumer pinned to an older peft, set `checkpoint.legacy_paramwrapper_layout: true` in the training config to export the pre-0.19.1 layout instead. An adapter exported that way does not load with peft 0.19.1 or newer.
+
 ```python
 import torch
 from transformers import AutoModelForCausalLM, AutoTokenizer
 
@@ -28,7 +28,12 @@
 )
 from nemo_automodel.components.checkpoint.state_dict_adapter import StateDictAdapter
 from nemo_automodel.components.checkpoint.stateful_wrappers import ModelState
-from nemo_automodel.components.moe.state_dict_mixin import MoESplitExpertsStateDictMixin
+from nemo_automodel.components.moe.state_dict_mixin import (
+    _PARAMWRAPPER_LAYOUT_LEGACY,
+    _PARAMWRAPPER_LAYOUT_METADATA_KEY,
+    _PARAMWRAPPER_LAYOUT_MODERN,
+    MoESplitExpertsStateDictMixin,
+)
 from nemo_automodel.shared.parameter_names import canonical_parameter_fqn
 
 if TYPE_CHECKING:
@@ -268,6 +273,12 @@ def pre_save(self, **kwargs) -> None:
         process_group = kwargs.get("process_group")
         hf_peft_config = _get_hf_peft_config(peft_config, model_state, v4_compatible=v4_compatible)
         automodel_peft_metadata = _get_automodel_peft_metadata(peft_config)
+        adapter = getattr(_unwrap_ddp_model(model_state.model[0]), "state_dict_adapter", None)
+        layout_stamp = _get_paramwrapper_layout_stamp(
+            adapter, v4_compatible, kwargs.get("legacy_paramwrapper_layout", False)
+        )
+        if layout_stamp is not None:
+            automodel_peft_metadata[_PARAMWRAPPER_LAYOUT_METADATA_KEY] = layout_stamp
         if _is_group_rank_0(process_group):
             # if the HF model has custom model code, we need to save it as part of the checkpoint
             model_part = model_state.model[0] if model_state is not None else None
@@ -354,6 +365,19 @@ def _get_hf_peft_config(peft_config: "PeftConfig", model_state: ModelState, v4_c
     return config
 
 
+def _get_paramwrapper_layout_stamp(adapter, v4_compatible: bool, legacy_paramwrapper_layout: bool) -> "str | None":
+    """Which fused expert LoRA layout this PEFT save uses, for the metadata stamp.
+
+    peft flipped the ParamWrapper layout in 0.19.1 (huggingface/peft#3165);
+    stamping the layout into automodel_peft_config.json lets the loader
+    resolve it from metadata instead of tensor shapes. Returns None for
+    adapters that don't emit fused (v5 ParamWrapper) expert LoRA at all.
+    """
+    if v4_compatible or not getattr(adapter, "_v5_peft_target_parameters", ()):
+        return None
+    return _PARAMWRAPPER_LAYOUT_LEGACY if legacy_paramwrapper_layout else _PARAMWRAPPER_LAYOUT_MODERN
+
+
 def _get_automodel_peft_metadata(peft_config: "PeftConfig") -> dict:
     """
     Get the PEFT metadata in the format expected by Automodel.
 
@@ -620,6 +620,7 @@ def save_model(
             quantization=False,
             device_mesh=self.moe_mesh,
             v4_compatible=self.config.v4_compatible,
+            legacy_paramwrapper_layout=self.config.legacy_paramwrapper_layout,
         )
         # MoE adapters return non-contiguous views; safetensors.save rejects those.
         _materialize_to_hf_views_for_save(state_dict)
@@ -646,6 +647,7 @@ def save_model(
                 fqn_to_dtype_mapping=fqn_to_dtype_mapping,
                 original_model_path=self._get_original_model_path(model_state),
                 v4_compatible=self.config.v4_compatible,
+                legacy_paramwrapper_layout=self.config.legacy_paramwrapper_layout,
                 process_group=consolidation_process_group,
             )
         self._maybe_write_offline_consolidation_script(model_dir)
@@ -880,7 +882,10 @@ def load_model(
             t_disk = time.monotonic()
             if state_dict_from_disk is not None:
                 state_dict_from_disk = _maybe_adapt_state_dict_from_hf(
-                    model_state.model[0], state_dict_from_disk, moe_mesh=self.moe_mesh
+                    model_state.model[0],
+                    state_dict_from_disk,
+                    moe_mesh=self.moe_mesh,
+                    paramwrapper_layout_hint=_read_paramwrapper_layout_metadata(model_path),
                 )
             else:
                 state_dict_from_disk = {}
@@ -1052,7 +1057,12 @@ def load_model(
         if compat_tied_lm_head_source_key is not None and isinstance(lm_head_param_name, str):
             state_dict[lm_head_param_name] = state_dict.pop(compat_tied_lm_head_source_key)
 
-        state_dict = _maybe_adapt_state_dict_from_hf(model_state.model[0], state_dict, moe_mesh=self.moe_mesh)
+        state_dict = _maybe_adapt_state_dict_from_hf(
+            model_state.model[0],
+            state_dict,
+            moe_mesh=self.moe_mesh,
+            paramwrapper_layout_hint=_read_paramwrapper_layout_metadata(model_path),
+        )
         adapter_complete = time.monotonic()
         expected_keys_for_diff = {k for k in expected_keys if not k.endswith("_extra_state")}
         loaded_keys_for_diff = {k for k in state_dict if not k.endswith("_extra_state")}
@@ -2785,14 +2795,41 @@ def _load_hf_bin_checkpoint(model_path: str) -> dict[str, torch.Tensor] | None:
 
 
 def _maybe_adapt_state_dict_from_hf(
-    model_part: nn.Module, state_dict: dict[str, torch.Tensor], moe_mesh: DeviceMesh | None = None
+    model_part: nn.Module,
+    state_dict: dict[str, torch.Tensor],
+    moe_mesh: DeviceMesh | None = None,
+    paramwrapper_layout_hint: str | None = None,
 ) -> dict[str, torch.Tensor]:
     """
     Custom models use state dict adapters to convert the state dict from the Hugging Face format to the native format.
+
+    ``paramwrapper_layout_hint`` carries the fused expert LoRA layout recorded in
+    the checkpoint's automodel_peft_config.json (see _read_paramwrapper_layout_metadata),
+    so the adapter resolves the peft ParamWrapper layout from metadata instead of shapes.
     """
     adapter = getattr(_unwrap_ddp_model(model_part), "state_dict_adapter", None)
     if adapter:
         ep_mesh_dims = [dim for dim in moe_mesh.mesh_dim_names if dim != "pp"] if moe_mesh is not None else []
         ep_mesh = moe_mesh[tuple(ep_mesh_dims)] if ep_mesh_dims else moe_mesh
-        return adapter.from_hf(state_dict, device_mesh=ep_mesh)
+        adapter._paramwrapper_layout_hint = paramwrapper_layout_hint
+        try:
+            return adapter.from_hf(state_dict, device_mesh=ep_mesh)
+        finally:
+            adapter._paramwrapper_layout_hint = None
     return state_dict
+
+
+def _read_paramwrapper_layout_metadata(model_path: str | os.PathLike) -> str | None:
+    """Return the fused expert LoRA layout stamped into a PEFT checkpoint, if any.
+
+    The PEFT save path records which peft ParamWrapper layout the adapter was
+    exported in (peft flipped it in 0.19.1, huggingface/peft#3165) inside
+    automodel_peft_config.json. Absent or unstamped checkpoints return None and
+    the adapter falls back to shape detection.
+    """
+    metadata_path = os.path.join(model_path, "automodel_peft_config.json")
+    try:
+        with open(metadata_path) as f:
+            return json.load(f).get("paramwrapper_layout")
+    except (FileNotFoundError, NotADirectoryError, json.JSONDecodeError):
+        return None
@@ -122,6 +122,9 @@ class CheckpointingConfig:
     staging_dir: str | None = None
     v4_compatible: bool = False  # If True, save the original pretrained config.json (with quantization_config removed)
     # instead of the in-memory v5 config.  Useful when downstream consumers (e.g. vLLM) expect a v4-format config.
+    legacy_paramwrapper_layout: bool = False  # If True, export fused expert LoRA (PEFT v5 ParamWrapper) weights in
+    # the pre-flip peft <= 0.19.0 layout instead of the corrected peft >= 0.19.1 layout (huggingface/peft#3165).
+    # Only for consumers pinned to an older peft; unrelated to v4_compatible.
     diffusers_compatible: bool = False  # If True, use diffusers-compatible index filename
     # (diffusion_pytorch_model.safetensors.index.json) so checkpoints are loadable via diffusers from_pretrained().
     best_metric_key: str = "default"  # Validation metric key used to select the best checkpoint.
 
@@ -81,7 +81,9 @@ def convert_single_tensor_to_hf(self, fqn: str, tensor: Any, **kwargs) -> list[t
 
         When ``v4_compatible=False`` (the default), LoRA expert tensors are
         emitted in PEFT v0.18+ ParamWrapper format so that
-        ``PeftModel.from_pretrained()`` can load them directly.  When
+        ``PeftModel.from_pretrained()`` can load them directly; the layout
+        follows peft >= 0.19.1 unless ``legacy_paramwrapper_layout=True``
+        asks for the pre-flip layout (huggingface/peft#3165).  When
         ``v4_compatible=True``, the legacy per-expert split is used instead
         (via the parent mixin).
 
@@ -101,7 +103,9 @@ def convert_single_tensor_to_hf(self, fqn: str, tensor: Any, **kwargs) -> list[t
             expert_segment = self._expert_path_segment
             for suffix in _LORA_EXPERT_SUFFIXES:
                 if fqn.endswith(f".{suffix}") and f".{expert_segment}.{suffix}" in fqn:
-                    result = self._convert_lora_to_paramwrapper(fqn, tensor)
+                    result = self._convert_lora_to_paramwrapper(
+                        fqn, tensor, legacy_layout=kwargs.get("legacy_paramwrapper_layout", False)
+                    )
                     if exclude_key_regex:
                         result = [(k, v) for k, v in result if not re.match(exclude_key_regex, k)]
                     return result