Registry / ai-ml / fairscale

fairscale

JSON →
library0.4.13pypypi✓ verified 27d ago

FairScale is a PyTorch extension library providing utilities for large-scale and high-performance training, including Fully Sharded Data Parallel (FSDP) and Optimizer State Sharding (OSS). While many features, especially FSDP, have been upstreamed to PyTorch, FairScale offers specialized tools for memory and communication efficiency. The current version is 0.4.13. Release cadence is infrequent now, as core functionalities are integrated into PyTorch.

pip install fairscale
INSTALL
IMPORT
SIG · FAIRSCALE
F
fairscale
ai-mlpythonv0.4.13
Install
71.1s avg
Import
6510ms
Disk
4813MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.9–3.13
musl
3.9–3.13
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
musl
glibc
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()
Debug
Known issues
deprecatedFairScale's FSDP (`fairscale.nn.data_parallel.FullyShardedDataParallel`) is largely superseded by PyTorch's native FSDP (`torch.distributed.fsdp.FullyShardedDataParallel`) since PyTorch 1.11 and 1.12+. For new projects, the native PyTorch implementation is strongly encouraged due to ongoing development and optimizations.
fix
Migrate your FSDP usage to `torch.distributed.fsdp.FullyShardedDataParallel`. Consult the official PyTorch FSDP documentation for migration guides and updated best practices.
affects: 0.4.0+
breakingFairScale is in maintenance mode, meaning active development for new features has largely shifted to PyTorch's native distributed modules. Future API changes or new features in PyTorch's core distributed components might not be backported or fully compatible with FairScale in the future.
fix
Plan for migration to native PyTorch distributed features, especially `torch.distributed.fsdp`, to ensure future compatibility, access to the latest optimizations, and bug fixes.
affects: 0.4.0+
gotchaFairScale requires a properly initialized `torch.distributed` environment. Running without `dist.init_process_group` (even for single-GPU FSDP) will result in errors or unexpected behavior during model wrapping or training.
fix
Ensure `torch.distributed.init_process_group` is called before instantiating FairScale's FSDP or OSS. Use environment variables (e.g., `MASTER_ADDR`, `MASTER_PORT`, `RANK`, `WORLD_SIZE`) or helper functions for distributed setup.
affects: All
gotchaWhen using FairScale's FSDP with mixed precision, ensure that the `mixed_precision` argument in `FSDP` is configured correctly, or that you are using a compatible `torch.cuda.amp.GradScaler` outside of FSDP, depending on your PyTorch version and specific setup. Incorrect configuration can lead to performance issues or `NaN` gradients.
fix
Refer to FairScale's documentation on mixed precision usage with FSDP. In many cases, `torch.cuda.amp` can be used alongside FSDP, but careful integration is required.
affects: All
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.
fix
Install 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.
fix
For 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.
fix
Ensure `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.
fix
Review 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.
fix
Consider 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.
Agent activity
17 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources