"imgs_per_gpu" is deprecated in MMDet V2.0. Please use "samp

Error message

"imgs_per_gpu" is deprecated in MMDet V2.0. Please use "samples_per_gpu" instead

What it means

compat_imgs_per_gpu warns that imgs_per_gpu, the MMDet V1.x batch-size key under cfg.data, is deprecated in V2.0 in favor of samples_per_gpu. It fires whenever 'imgs_per_gpu' is present in cfg.data, before it copies the value over (and possibly warns about a conflict, see error 325).

Source

Thrown at mmdet/utils/compat_config.py:40

def compat_runner_args(cfg):
    if 'runner' not in cfg:
        cfg.runner = ConfigDict({
            'type': 'EpochBasedRunner',
            'max_epochs': cfg.total_epochs
        })
        warnings.warn(
            'config is now expected to have a `runner` section, '
            '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:

View on GitHub (pinned to cfd5d3a985)

Solutions

Rename the key in your config: data = dict(..., samples_per_gpu=N) and delete imgs_per_gpu.
If both keys exist, remove imgs_per_gpu to avoid the follow-up conflict warning (error 325).
Note samples_per_gpu can also be split per split (train_dataloader=dict(samples_per_gpu=...) in later versions) — follow your installed version's config style.
Run mmcv.Config.fromfile(...).data on the sanitized config to confirm only samples_per_gpu remains.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

from mmcv import Config

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

Prevention

Write samples_per_gpu (not imgs_per_gpu) in all new mmdet 2.x configs.
grep -r imgs_per_gpu configs/ during migrations to catch stragglers.
Validate configs load cleanly via Config.fromfile before launching long training jobs.

When it happens

Trigger: Any tools/train.py / tools/test.py invocation (both call compat_cfg → compat_imgs_per_gpu) with a config containing data = dict(..., imgs_per_gpu=N). The warning is emitted unconditionally once the key exists.

Common situations: Using legacy or third-party configs written for MMDet 1.x with a 2.x install; upgrading a project across the V1→V2 boundary; copying old detection challenge baseline configs.

Related errors

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