deepinsight/insightface · error · ImportError

The rec.addmaskparam command requires optional mask renderin

Error message

The rec.addmaskparam command requires optional mask rendering and MXNet record dependencies. Please install the required optional dependencies before running this command.

What it means

The second guard in rec.addmaskparam.run(): mxnet imports fine, but importing insightface's optional mask-rendering modules (..app.mask_renderer.MaskRenderer, ..data.rec_builder.RecBuilder) fails, so the command re-raises ImportError citing optional dependencies. The optional mask-rendering stack is present in name but its transitive deps are missing or incompatible.

Source

Thrown at python-package/insightface/commands/rec_add_mask_param.py:47

        output: str,
    ):
        self._input = input
        self._output = output


    def run(self):
        try:
            import mxnet as mx
        except ImportError as exc:
            raise ImportError(
                "The rec.addmaskparam command requires mxnet. "
                "Please install mxnet before running this command."
            ) from exc
        try:
            from ..app.mask_renderer import MaskRenderer
            from ..data.rec_builder import RecBuilder
        except ImportError as exc:
            raise ImportError(
                "The rec.addmaskparam command requires optional mask rendering "
                "and MXNet record dependencies. Please install the required "
                "optional dependencies before running this command."
            ) from exc

        tool = MaskRenderer()
        tool.prepare(ctx_id=0, det_size=(128,128))
        root_dir = self._input
        path_imgrec = os.path.join(root_dir, 'train.rec')
        path_imgidx = os.path.join(root_dir, 'train.idx')
        imgrec = mx.recordio.MXIndexedRecordIO(path_imgidx, path_imgrec, 'r')
        save_path = self._output
        wrec=RecBuilder(path=save_path)
        s = imgrec.read_idx(0)
        header, _ = mx.recordio.unpack(s)
        if header.flag > 0:
            if len(header.label)==2:
                imgidx = np.array(range(1, int(header.label[0])))

View on GitHub (pinned to 7fadd420c2)

Solutions

Run 'python -c "from insightface.app.mask_renderer import MaskRenderer; from insightface.data.rec_builder import RecBuilder"' to surface the underlying missing module and install it.
Pin compatible versions: mxnet<2.0, opencv-contrib-python, numpy<2.
Reinstall insightface from source so all bundled submodules are present: pip install -e .
Run the command in the legacy Python 3.8 container recommended for insightface training tools.

Example fix

# before
insightface rec.addmaskparam ...  # ImportError: requires optional mask rendering and MXNet record dependencies

# after
pip install opencv-contrib-python 'mxnet<2.0' 'numpy<2'
insightface rec.addmaskparam ...

Defensive patterns

Strategy: validation

Validate before calling

try:
    from insightface.app.mask_renderer import MaskRenderer
    from insightface.data.rec_builder import RecBuilder
    ok = True
except ImportError:
    ok = False
assert ok, 'install optional deps: opencv-contrib-python "mxnet<2.0" "numpy<2"'

Try / catch

try:
    from insightface.app.mask_renderer import MaskRenderer
except ImportError as e:
    raise RuntimeError(f'mask-rendering extras missing ({e}); pip install opencv-contrib-python "mxnet<2.0"') from e

Prevention

Install the full training-extras set in one pinned requirements file.
Smoke-test optional imports at startup with an actionable message.

When it happens

Trigger: Running rec.addmaskparam where 'import mxnet' succeeds but 'from ..app.mask_renderer import MaskRenderer' or 'from ..data.rec_builder import RecBuilder' raises ImportError — missing opencv-contrib, mxnet version incompatible with the record IO code, or a partial insightface install.

Common situations: Installing insightface without training extras; mxnet 2.x vs 1.x API mismatch in rec_builder; cv2 import failing due to missing system libs; numpy 2.x breaking old mxnet/record tooling.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

AI-assisted analysis of deepinsight/insightface@7fadd420c2 (2026-08-28). Data as JSON: /api/errors/25e23e419ee4f998. Report an issue: GitHub.