Install & Compatibility
Where this runs
tested against v0.4.13 · 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
py 3.10
✕ build_error
✓ 80.6s
py 3.11
✕ build_error
✓ 72.3s
py 3.12
✕ build_error
✓ 69.2s
py 3.13
✕ build_error
✓ 62.4s
py 3.9
✕ build_error
✕ timeout
4813MB installed
● package 4813MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FullyShardedDataParallel
✓ from fairscale.nn.data_parallel import FullyShardedDataParallel
✗ from fairscale.nn import FullyShardedDataParallel
FairScale's FSDP implementation is nested under the `data_parallel` submodule.
OSS
✓ from fairscale.optim.oss import OSS
This quickstart demonstrates how to wrap a PyTorch model with FairScale's Fully Sharded Data Parallel (FSDP) and its Optimizer State Sharding (OSS) for memory-efficient training. Note that `dist.init_process_group` is essential for multi-GPU/node training; a dummy initialization is used here for a runnable single-process example. For new projects, it is highly recommended to consider migrating to PyTorch's native FSDP.
import torch
import torch.nn as nn
import torch.distributed as dist
from fairscale.nn.data_parallel import FullyShardedDataParallel as FSDP
from fairscale.optim.oss import OSS
# NOTE: For actual distributed use, dist.init_process_group must be called for multi-GPU/node setups.
# This example simulates a single-process setup for quickstart.
# In a real distributed run, rank and world_size would come from the environment.
# Dummy initialization for single-process quickstart
if not dist.is_initialized():
try:
# Using HashStore for a simple single-node, single-process initialization
dist.init_process_group(backend='gloo', rank=0, world_size=1, store=dist.HashStore())
except RuntimeError as e:
# Catch if already initialized (e.g., in some interactive environments)
print(f"Could not initialize process group (might be already initialized): {e}")
# 1. Define a simple model
class MyModel(nn.Module):
def __init__(self):
super().__init__()
self.layer = nn.Linear(10, 10)
def forward(self, x):
return self.layer(x)
# 2. Instantiate the model
model = MyModel()
# 3. Wrap the model with FairScale's FSDP
# For simplicity, default options are used. Real-world usage often requires careful tuning.
fsdp_model = FSDP(model)
# 4. Wrap the optimizer with FairScale's OSS
optimizer = torch.optim.Adam(fsdp_model.parameters(), lr=1e-3)
oss_optimizer = OSS(params=fsdp_model.parameters(), optim=optimizer)
# 5. Dummy data and training step
input_data = torch.randn(2, 10)
labels = torch.randn(2, 10)
# Forward pass
output = fsdp_model(input_data)
loss = nn.MSELoss()(output, labels)
# Backward pass and optimizer step
oss_optimizer.zero_grad()
loss.backward()
oss_optimizer.step()
print(f"FairScale FSDP and OSS example completed. Loss: {loss.item():.4f}")
# Clean up distributed environment if it was initialized by this script
if dist.is_initialized() and dist.get_world_size() == 1:
dist.destroy_process_group()
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fairscale'
The FairScale library is not installed in your current Python environment, or the environment where it was installed is not active.
fixInstall FairScale using pip: `pip install fairscale` or `pip install fairscale==0.4.13` for the specific version. Ensure your virtual environment is activated if applicable.
fairscale FSDP deprecated
FairScale's FSDP (`fairscale.nn.data_parallel.FullyShardedDataParallel`) has largely been superseded by PyTorch's native FSDP (`torch.distributed.fsdp.FullyShardedDataParallel`) since PyTorch 1.11 and 1.12+. FairScale is in maintenance mode, with active development shifting to PyTorch's native distributed modules.
fixFor new projects, use `torch.distributed.fsdp.FullyShardedDataParallel`. For existing projects, plan for migration to native PyTorch FSDP to ensure future compatibility and access to latest optimizations.
RuntimeError: Default process group has not been initialized
FairScale, especially FSDP, requires a properly initialized `torch.distributed` environment. This error occurs if `torch.distributed.init_process_group` has not been called before instantiating FairScale's FSDP or OSS modules.
fixEnsure `torch.distributed.init_process_group` is called early in your distributed training setup, providing necessary parameters like `backend`, `init_method`, `rank`, and `world_size`.
AttributeError: 'FlatParameter' object has no attribute '_full_param_padded'
This error typically arises from internal inconsistencies or incompatible usage patterns with `FullyShardedDataParallel`, possibly related to how parameters are flattened and managed internally, or specific versions of PyTorch/FairScale.
fixReview your FSDP wrapping strategy, especially with nested modules or activation checkpointing. Ensure compatibility between your PyTorch and FairScale versions. Consider updating FairScale or adapting to PyTorch's native FSDP which might resolve underlying parameter management issues.
Out Of Memory Error (FairScale FSDP)
Despite using FSDP for memory efficiency, large models or specific training configurations (e.g., high batch size, long sequences, lack of mixed precision) can still lead to GPU Out Of Memory (OOM) errors.
fixConsider reducing batch size, enabling mixed precision training (e.g., `mixed_precision=True` in FSDP, `torch.cuda.amp.autocast`), using CPU offloading (`cpu_offload=True`), implementing activation checkpointing, or strategically wrapping layers in FSDP to optimize memory usage.
Upgrade
Version history
0.4.13latest on PyPI · released Dec 11, 2022
Audit
Dependencies
torchrequiredCore deep learning framework. Requires torch>=1.11 for full compatibility.