Build1 publisher2 min readPublished Updated
ShadowPEFT reaches PEFT's main branch as an adapter that keeps its own hidden state
ShadowPEFT is in Hugging Face PEFT's main branch as of a September 15th announcement, and it carries its own hidden state and can be detached as a smaller standalone model. Trying it means installing PEFT from source.
The Engineer · Build desk

What happened
- Xianming Li, Zongxi Li and Tsz-fung Andrew Lee brought ShadowPEFT into the main branch of Hugging Face's PEFT library, a way to fine-tune a large model through a smaller trainable one.
- The shadow network receives task supervision during training and can be pulled out with unload_shadow() as a smaller predictor that runs without the large base model at all.
- The code sits in PEFT's development branch and is slated for the next release, so anyone on the regular package has to install PEFT from source to test it.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- cost The extra compute and memory are permanent for anyone serving the pair, because the parallel network wraps whole decoder blocks and stays in the forward pass at inference as well as during training.
- constraint Teams whose serving path folds an adapter into the base weights before deployment need a different plan for this one, since PEFT refuses the merge calls outright.
- capability One training run can now leave you with two deployable artifacts, a heavy pair and a cheap detached predictor, and only Transformers language models get the cheap one.
- contradiction Serving numbers taken from the standalone ShadowPEFT repository will understate what the library can do, because its documentation still describes generation with caching disabled while the main-branch code decodes with two KV caches.
LoRA expresses an adaptation as low-rank changes attached to selected model weights, and the adapter does not carry a single task-specific state from one layer to the next [5]. ShadowPEFT gives that job to a compact network: it creates a hidden state, injects information from that state into each frozen Transformer block, and updates the state using the block's output, so the base model and the shadow exchange information throughout the forward pass [6]. Because the state changes with every input, there is no fixed delta to fold into the frozen weights, and PEFT's documentation raises an explicit error for `merge`, `merge_adapter` and `merge_and_unload` [11][12].
The second output is what makes the design interesting. The shadow network receives task supervision during training and can be extracted with `unload_shadow()` as a smaller predictor that runs without the large base [8]. Hugging Face's example pairs a Qwen3-8B base with a Qwen3-0.6B shadow, using a learned projection when the hidden dimensions differ [9]. Going by the parameter counts in those names, the detached model is roughly one thirteenth the size of the backbone it was trained behind [20].
The benchmarks are author-reported. The team's figures come from a MetaMathQA-to-GSM8K experiment on Llama 3.2 3B and favor ShadowPEFT, with a higher memory cost [16]. For that to transfer, your job would have to look like single-task supervised fine-tuning on a base of about that size, and your training budget would need headroom for a network that wraps whole decoder blocks instead of attaching to selected matrices [11]. The paper was first submitted on April 21st and revised on September 11th [7].
Adoption cost is low in the places teams usually feel it. ShadowPEFT works through `get_peft_model`, and checkpoints use PEFT's standard `save_pretrained` and `from_pretrained` paths [10]. It is in the development branch and slated for the next release, so trying it today means installing PEFT from source into an environment whose main attraction was that you did not have to [4].
According to runtimewire.com, citing the Hugging Face Newsroom, native support puts the method in the fine-tuning workflow developers already run, which gives the research team distribution and exposes the method to broader testing [17]. Lee submitted the integration pull request, which added support for incremental generation and Hugging Face's existing adapter interfaces [3]. The group has six members; Jing Li founded the PolyU Embodied Artificial Intelligence Lab after working as a senior researcher at Tencent AI Lab, and Qing Li heads Hong Kong Polytechnic University's Department of Computing [18][19].
What to watch
- Whether ShadowPEFT ships in PEFT's next tagged release, and whether the API changes between the development branch and that tag.
- An independent reproduction of the MetaMathQA-to-GSM8K result on a base other than Llama 3.2 3B.
- Whether unload_shadow() gains a path for Diffusers models.