Automatically set "samples_per_gpu"="imgs_per_gpu"={cfg.data

Error message

Automatically set "samples_per_gpu"="imgs_per_gpu"={cfg.data.imgs_per_gpu} in this experiments

What it means

The non-conflict branch of compat_imgs_per_gpu: imgs_per_gpu exists, samples_per_gpu does not, so the shim sets cfg.data.samples_per_gpu = cfg.data.imgs_per_gpu and informs you of the automatic mapping. Behavior is correct — this is a migration notice so you update the config to V2 naming.

Source

Thrown at mmdet/utils/compat_config.py:48

            'please set `runner` in your config.', UserWarning)
    else:
        if 'total_epochs' in cfg:
            assert cfg.total_epochs == cfg.runner.max_epochs
    return cfg


def compat_imgs_per_gpu(cfg):
    cfg = copy.deepcopy(cfg)
    if 'imgs_per_gpu' in cfg.data:
        warnings.warn('"imgs_per_gpu" is deprecated in MMDet V2.0. '
                      'Please use "samples_per_gpu" instead')
        if 'samples_per_gpu' in cfg.data:
            warnings.warn(
                f'Got "imgs_per_gpu"={cfg.data.imgs_per_gpu} and '
                f'"samples_per_gpu"={cfg.data.samples_per_gpu}, "imgs_per_gpu"'
                f'={cfg.data.imgs_per_gpu} is used in this experiments')
        else:
            warnings.warn('Automatically set "samples_per_gpu"="imgs_per_gpu"='
                          f'{cfg.data.imgs_per_gpu} in this experiments')
        cfg.data.samples_per_gpu = cfg.data.imgs_per_gpu
    return cfg


def compat_loader_args(cfg):
    """Deprecated sample_per_gpu in cfg.data."""

    cfg = copy.deepcopy(cfg)
    if 'train_dataloader' not in cfg.data:
        cfg.data['train_dataloader'] = ConfigDict()
    if 'val_dataloader' not in cfg.data:
        cfg.data['val_dataloader'] = ConfigDict()
    if 'test_dataloader' not in cfg.data:
        cfg.data['test_dataloader'] = ConfigDict()

    # special process for train_dataloader
    if 'samples_per_gpu' in cfg.data:

View on GitHub (pinned to cfd5d3a985)

Solutions

Rename imgs_per_gpu to samples_per_gpu in the config to silence the notice.
Keep going as-is if you accept the compat behavior — training uses batch size N correctly.
Audit related legacy keys at the same time (total_epochs, workers_per_gpu naming, runner) to fully modernize the config.
Prefer split-specific settings (e.g. data = dict(train_dataloader=dict(samples_per_gpu=N))) in newer mmdet versions.

Example fix

# before
data = dict(imgs_per_gpu=4, ...)
# after
data = dict(samples_per_gpu=4, ...)

Defensive patterns

Strategy: validation

Validate before calling

from mmcv import Config

def ensure_samples_per_gpu(cfg: Config) -> Config:
    if 'imgs_per_gpu' in cfg.data and 'samples_per_gpu' not in cfg.data:
        cfg.data.samples_per_gpu = cfg.data.pop('imgs_per_gpu')
    return cfg

Prevention

Rename imgs_per_gpu to samples_per_gpu once and commit, to stop relying on compat shims.
Track which config keys your mmdet version expects via its official template configs.

When it happens

Trigger: tools/train.py or tools/test.py with a config containing only data = dict(..., imgs_per_gpu=N). After this warning the config behaves as if samples_per_gpu=N were set.

Common situations: Running unmodified legacy V1.x configs on MMDet 2.x for a quick reproduction; old tutorial/notebook configs.

Related errors

AI-assisted analysis of open-mmlab/mmdetection@cfd5d3a985 (2026-08-27). Data as JSON: /api/errors/86329ecd0a412f80. Report an issue: GitHub.