Install & Compatibility
Where this runs
tested against v0.11.0 · 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
✓ 76.3s
py 3.11
✕ build_error
✓ 69.3s
py 3.12
✕ build_error
✓ 63.6s
py 3.13
✕ build_error
✓ 57.1s
py 3.9
✕ build_error
✕ timeout
4710MB installed
● package 4710MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StatefulDataLoader
✓ from torchdata.stateful_dataloader import StatefulDataLoader
nodes
✓ import torchdata.nodes as nodes
Represents the new direction for building data pipelines with composable iterators.
DataPipes
✓ from torchdata.datapipes.iter import IterableWrapper
✗ from torchdata.datapipes.iter import ...
DataPipes are deprecated and largely removed starting from v0.9.0. Migrate to `torchdata.nodes` or `StatefulDataLoader`.
DataLoader2
✓ from torchdata.dataloader2 import DataLoader2
✗ from torchdata.dataloader2 import DataLoader2
DataLoader2 is deprecated and largely removed starting from v0.9.0. Use `StatefulDataLoader` or standard `torch.utils.data.DataLoader` instead.
This quickstart demonstrates how to use `StatefulDataLoader`, which is a key enhancement of `torch.utils.data.DataLoader` provided by TorchData. It's a drop-in replacement that adds checkpointing capabilities.
import torch
from torch.utils.data import TensorDataset
from torchdata.stateful_dataloader import StatefulDataLoader
# Create a dummy dataset
data = torch.randn(100, 10)
labels = torch.randint(0, 2, (100,))
dataset = TensorDataset(data, labels)
# Use StatefulDataLoader as a drop-in replacement for torch.utils.data.DataLoader
batch_size = 16
dataloader = StatefulDataLoader(
dataset,
batch_size=batch_size,
shuffle=True,
num_workers=0 # For simplicity, use 0 workers
)
print(f"Number of batches: {len(dataloader)}")
# Iterate through the data
for epoch in range(2):
print(f"\nEpoch {epoch + 1}")
for i, (batch_data, batch_labels) in enumerate(dataloader):
if i % 10 == 0:
print(f" Batch {i}: data_shape={batch_data.shape}, labels_shape={batch_labels.shape}")
# In a real scenario, perform training steps here
# Example of saving and loading state (checkpointing)
# This is a key feature of StatefulDataLoader
state = dataloader.state_dict()
print(f"\nSaved dataloader state: {state.keys()}")
# Simulate continued training or restart
new_dataloader = StatefulDataLoader(dataset, batch_size=batch_size, shuffle=True, num_workers=0)
new_dataloader.load_state_dict(state)
print("Loaded dataloader state.")
# Iteration will resume from where it left off
print("Resuming iteration (should continue from saved state):")
for i, (batch_data, batch_labels) in enumerate(new_dataloader):
if i < 3:
print(f" Resumed Batch {i}: data_shape={batch_data.shape}, labels_shape={batch_labels.shape}")
Debug
Known issues
breakingDataPipes and DataLoader2, which were core components of earlier TorchData versions, have been largely removed from the library starting with version 0.9.0. They were marked as deprecated in v0.8.0. Subsequent releases, including 0.11.0, do not include or maintain these solutions.fixMigrate existing pipelines to `torchdata.nodes` or leverage `StatefulDataLoader` as an enhancement to `torch.utils.data.DataLoader`. If you must use DataPipes/DataLoader2, pin your dependency to `torchdata<=0.8.0`.
affects: >=0.9.0
breakingPython 3.8 support was dropped in TorchData v0.9.0.fixUpgrade your Python environment to version 3.9 or newer. The current release (0.11.0) requires Python >=3.9.
affects: >=0.9.0
deprecatedTorchData has deprecated and removed its conda builds, as PyTorch's official conda channel itself is deprecated.fixInstall TorchData via pip from PyPI: `pip install torchdata`.
affects: All versions
gotchaBe aware of specific behaviors in `StatefulDataLoader` related to `num_workers=0` and initial seeding for `RandomSampler` during state loading. These can lead to unexpected iteration patterns if not handled carefully.fixRefer to the official documentation for `StatefulDataLoader` regarding checkpointing and worker/seed management to ensure deterministic and correct resumption of training. Test your checkpointing logic thoroughly.
affects: 0.8.0, 0.11.0 (and potentially others)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'torchdata'
The torchdata library is not installed in your current Python environment.
ModuleNotFoundError: No module named 'torch.utils.data.dataloader2'
The DataLoader2 component was moved from `torch.utils.data` to `torchdata.dataloader2` in newer versions of the torchdata library.
fixfrom torchdata.dataloader2 import DataLoader2
ImportError: cannot import name 'IterDataPipe' from 'torchdata.datapipes'
DataPipes like IterDataPipe are located within specific submodules such as `torchdata.datapipes.iter`, not directly under `torchdata.datapipes`.
fixfrom torchdata.datapipes.iter import IterDataPipe
TypeError: 'IterDataPipe' object is not iterable
An IterDataPipe instance itself is not directly iterable like a standard Python list or generator; it needs to be wrapped by a DataLoader (e.g., DataLoader2) to produce batches of data.
fixfrom torchdata.dataloader2 import DataLoader2
dl = DataLoader2(my_iter_datapipe)
for item in dl:
# Process item
... Upgrade
Version history
0.11.0latest on PyPI · released Feb 20, 2025
Audit
Dependencies
torchrequiredTorchData is built to extend PyTorch's data loading capabilities and is a core part of the PyTorch ecosystem.