pytorch-fsdp2

Adds PyTorch FSDP2 fully_shard sharding, mixed precision, and distributed checkpointing to training scripts.

1|Updated Mar 5, 2026
One-click install
npx skills add https://github.com/Clay-HHK/claude-skills --skill pytorch-fsdp2-clay-hhk
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: pytorch-fsdp2
Source: https://github.com/Clay-HHK/claude-skills/tree/main/pytorch-fsdp2
Command: npx skills add https://github.com/Clay-HHK/claude-skills --skill pytorch-fsdp2-clay-hhk

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires torch, and includes references (resource) components.

What problem does it solve? Training large models that exceed single-GPU memory requires correct parameter sharding, and misusing PyTorch FSDP2 (wrong sharding order, optimizer timing, or naive checkpointing) causes memory blowups, silent hook failures, and broken checkpoints. ## Core Features & Use Cases - Correct FSDP2 Integration: Applies fully_shard() bottom-up with proper process group init, DeviceMesh setup, and meta-device model initialization. - Memory & Performance Tuning: Configures reshard_after_forward, MixedPrecisionPolicy, and CPUOffloadPolicy for memory/throughput trade-offs. - Distributed Checkpointing: Implements DCP save/load and distributed state-dict helpers with load-time resharding support. - Use Case: You have a transformer training script that OOMs on one GPU. Use this Skill to retrofit FSDP2 sharding, BF16 mixed precision, and DCP checkpointing so it trains across multiple GPUs. ## Quick Start Add PyTorch FSDP2 fully_shard sharding with distributed checkpointing to my training script so the model fits across multiple GPUs.

Frequently Asked Questions about pytorch-fsdp2

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add PyTorch FSDP2 to an existing training script?▼

Initialize the process group with torchrun, set the CUDA device from LOCAL_RANK, apply fully_shard() bottom-up to submodules then the root module, and create the optimizer after sharding so it holds DTensor parameters. Call model(input) rather than model.forward(input) so FSDP2 hooks run.

What is the difference between FSDP2 and FSDP1 in PyTorch?▼

FSDP2 uses DTensor per-parameter sharding instead of FSDP1's flat-parameter approach, giving more inspectable sharded state dicts and deterministic memory behavior. FSDP1's no_sync() maps to set_requires_gradient_sync, and sharding_strategy maps to reshard_after_forward.

How do I checkpoint an FSDP2 model with DTensor parameters?▼

Use Distributed Checkpoint (DCP) via torch.distributed.checkpoint, which saves from multiple ranks in parallel and supports load-time resharding. Alternatively use get_model_state_dict and set_model_state_dict helpers; avoid plain torch.save on DTensor state dicts.

Why does my FSDP2 model use more memory than expected?▼

Common causes are applying fully_shard only to the root module instead of bottom-up, or keeping reshard_after_forward=False on too many modules. Shard submodules first and set reshard_after_forward=True on memory-heavy blocks.

Can FSDP2 be combined with Tensor Parallelism?▼

Yes, using a 2D DeviceMesh where TP runs intra-host over fast interconnects and FSDP2 shards across the data-parallel dimension. Pass only the DP submesh to fully_shard and apply TP via parallelize_module.