open-mmlab/mmdetection · error · ImportError

Please run "pip install instaboostfast" to install instaboos

Error message

Please run "pip install instaboostfast" to install instaboostfast first for instaboost augmentation.

What it means

MMDetection's InstaBoost transform requires the third-party `instaboostfast` package. The __init__ of InstaBoost tries to import it and raises ImportError with install instructions if the package is missing. instaboostfast itself is not pip-installable from PyPI in some versions and may need to be built from source.

Source

Thrown at mmdet/datasets/transforms/instaboost.py:67

    def __init__(self,
                 action_candidate: tuple = ('normal', 'horizontal', 'skip'),
                 action_prob: tuple = (1, 0, 0),
                 scale: tuple = (0.8, 1.2),
                 dx: int = 15,
                 dy: int = 15,
                 theta: tuple = (-1, 1),
                 color_prob: float = 0.5,
                 hflag: bool = False,
                 aug_ratio: float = 0.5) -> None:

        import matplotlib
        import matplotlib.pyplot as plt
        default_backend = plt.get_backend()

        try:
            import instaboostfast as instaboost
        except ImportError:
            raise ImportError(
                'Please run "pip install instaboostfast" '
                'to install instaboostfast first for instaboost augmentation.')

        # instaboost will modify the default backend
        # and cause visualization to fail.
        matplotlib.use(default_backend)

        self.cfg = instaboost.InstaBoostConfig(action_candidate, action_prob,
                                               scale, dx, dy, theta,
                                               color_prob, hflag)
        self.aug_ratio = aug_ratio

    def _load_anns(self, results: dict) -> Tuple[list, list]:
        """Convert raw anns to instaboost expected input format."""
        anns = []
        ignore_anns = []
        for instance in results['instances']:
            label = instance['bbox_label']

View on GitHub (pinned to cfd5d3a985)

Solutions

pip install instaboostfast (from PyPI if available)
If PyPI install/build fails, clone https://github.com/albumentations-team/instaboostfast and install from source, ensuring numpy/opencv/python headers are available
If you don't need the augmentation, remove dict(type='InstaBoost', ...) from the train pipeline in your config

Example fix

// before (config pipeline)
train_pipeline=[dict(type='InstaBoost', aug_prob=0.5)]
// after
train_pipeline=[dict(type='RandomFlip', prob=0.5)]

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('instaboostfast') is None:
    # skip InstaBoost or install before training
    pass

Prevention

Check optional deps with importlib.util.find_spec before building the pipeline
Keep an environment.yml listing augmentation extras like instaboostfast

When it happens

Trigger: Instantiating the InstaBoost transform (e.g. via a pipeline config containing dict(type='InstaBoost', ...)) in an environment where `import instaboostfast` fails because the package is not installed or its compiled dependencies are missing.

Common situations: Using old mmdet configs that relied on InstaBoost augmentation; fresh conda/venv environments; instaboostfast failing to build against a new numpy/opencv version; copying a training pipeline from a repo that used instaboost.

Related errors

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