huggingface/pytorch-image-models · error · RuntimeError

Please install webdataset 0.2.x package `pip install git+htt

Error message

Please install webdataset 0.2.x package `pip install git+https://github.com/webdataset/webdataset`.

What it means

ReaderWds requires the third-party webdataset package; the import failed (wds is None), so __init__ raises immediately with install instructions pinned to the 0.2.x line that timm's reader is built against.

Source

Thrown at timm/data/readers/reader_wds.py:284

            name: Optional[str] = None,
            split: str = 'train',
            is_training: bool = False,
            num_samples: Optional[int] = None,
            batch_size: int = 1,
            repeats: int = 0,
            seed: int = 42,
            class_map: Optional[dict] = None,
            input_key: str = 'jpg;png;webp',
            input_img_mode: str = 'RGB',
            target_key: str = 'cls',
            target_img_mode: str = '',
            filename_key: str = 'filename',
            sample_shuffle_size: Optional[int] = None,
            sample_initial_size: Optional[int] = None,
    ):
        super().__init__()
        if wds is None:
            raise RuntimeError(
                'Please install webdataset 0.2.x package `pip install git+https://github.com/webdataset/webdataset`.')
        self.root = root
        self.is_training = is_training
        self.batch_size = batch_size
        self.repeats = repeats
        self.common_seed = seed  # a seed that's fixed across all worker / distributed instances
        self.shard_shuffle_size = 500
        self.sample_shuffle_size = sample_shuffle_size or SAMPLE_SHUFFLE_SIZE
        self.sample_initial_size = sample_initial_size or SAMPLE_INITIAL_SIZE

        self.input_key = input_key
        self.input_img_mode = input_img_mode
        self.target_key = target_key
        self.filename_key = filename_key
        self.key_ext = '.JPEG'  # extension to add to key for original filenames (DS specific, default ImageNet)

        self.info = _load_info(self.root)
        self.split_info = _parse_split_info(split, self.info)

View on GitHub (pinned to 9a5261e31b)

Solutions

1. pip install git+https://github.com/webdataset/webdataset (as the message suggests) or pip install 'webdataset>=0.2,<0.3'.
2. If install fails, check for dependency conflicts (e.g. braceexpand, msgpack) and retry in a clean venv.
3. Verify with python -c "import webdataset; print(webdataset.__version__)".

Example fix

pip install 'webdataset>=0.2,<0.3'
# then retry creating the reader

try:
    import webdataset as wds
except ImportError:
    raise SystemExit('pip install webdataset>=0.2,<0.3')

try:
    reader = ReaderWds(root, split='train')
except RuntimeError as e:
    if 'webdataset' in str(e):
        subprocess.check_call([sys.executable,'-m','pip','install','webdataset>=0.2,<0.3'])
    raise

When it happens

Trigger: Constructing ReaderWds (directly or via create_dataset(..., dataset_name='wds')) in an environment where webdataset is not installed or failed to import.

Common situations: Fresh timm install without the extras; a broken webdataset install (dependency conflict, partial pip failure); installing webdataset 0.1.x/other incompatible majors that fail to import alongside the installed timm.

Related errors

• split {split} not found in info ({info.get('splits', {}).key
• Invalid split definition, num_samples not specified in train
• Input image must have positive dimensions, got H={height}, W
• Invalid class map file, expected a dict ({class_map_path}).
• Dataset length is unknown, please pass `num_samples` explici

AI-assisted analysis of huggingface/pytorch-image-models@9a5261e31b (2026-08-27). Data as JSON: /api/errors/6bae477c97d4ea39. Report an issue: GitHub.