deepinsight/insightface · error · ImportError

The rec.addmaskparam command requires mxnet. Please install

Error message

The rec.addmaskparam command requires mxnet. Please install mxnet before running this command.

What it means

The rec.addmaskparam CLI command lazily does 'import mxnet as mx' inside run(); mxnet is deprecated and not a default dependency, so its absence is re-raised as this actionable ImportError. mxnet is needed to build mask-rendering params into recognition training records.

Source

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

        _parser = parser.add_parser("rec.addmaskparam")
        _parser.add_argument("input", type=str, help="input rec")
        _parser.add_argument("output", type=str, help="output rec, with mask param")
        _parser.set_defaults(func=rec_add_mask_param_command_factory)

    def __init__(
        self,
        input: str,
        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')

View on GitHub (pinned to 7fadd420c2)

Solutions

pip install mxnet (or mxnet-cu112 etc. for GPU) in the command's environment — py<=3.8 may be required to find wheels.
Use a dedicated Python 3.7/3.8 env or docker image for this legacy command.
Generate the mask params once in an mxnet-equipped container and reuse the produced record elsewhere.

Example fix

# before
insightface rec.addmaskparam --root ./ms1m  # ImportError: requires mxnet

# after
pip install mxnet==1.9.1
insightface rec.addmaskparam --root ./ms1m

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util
if importlib.util.find_spec('mxnet') is None:
    raise SystemExit('rec.addmaskparam needs mxnet: pip install mxnet (py<=3.8)')

Try / catch

try:
    subprocess.run(['insightface', 'rec.addmaskparam', '--root', root], check=True)
except subprocess.CalledProcessError:
    # rerun inside a legacy mxnet-equipped container
    ...

Prevention

Keep a dedicated py3.7/3.8 env or docker image with mxnet for legacy training tools.
Check importability of heavy optional deps before launching the CLI.

When it happens

Trigger: Running 'insightface rec.addmaskparam ...' in an environment where 'import mxnet' raises ImportError.

Common situations: Modern installs (mxnet has no wheels for py>=3.9 or Apple Silicon); following legacy mask-recognition training docs without installing mxnet; optional extras never pulled in by pip.

Related errors

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