{"record":{"id":"41d3e4f708cb1519","repo":"deepinsight/insightface","slug":"the-rec-addmaskparam-command-requires-mxnet-pleas","errorCode":null,"errorMessage":"The rec.addmaskparam command requires mxnet. Please install mxnet before running this command.","messagePattern":"The rec\\.addmaskparam command requires mxnet\\. Please install mxnet before running this command\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"python-package/insightface/commands/rec_add_mask_param.py","lineNumber":39,"sourceCode":"        _parser = parser.add_parser(\"rec.addmaskparam\")\n        _parser.add_argument(\"input\", type=str, help=\"input rec\")\n        _parser.add_argument(\"output\", type=str, help=\"output rec, with mask param\")\n        _parser.set_defaults(func=rec_add_mask_param_command_factory)\n\n    def __init__(\n        self,\n        input: str,\n        output: str,\n    ):\n        self._input = input\n        self._output = output\n\n\n    def run(self):\n        try:\n            import mxnet as mx\n        except ImportError as exc:\n            raise ImportError(\n                \"The rec.addmaskparam command requires mxnet. \"\n                \"Please install mxnet before running this command.\"\n            ) from exc\n        try:\n            from ..app.mask_renderer import MaskRenderer\n            from ..data.rec_builder import RecBuilder\n        except ImportError as exc:\n            raise ImportError(\n                \"The rec.addmaskparam command requires optional mask rendering \"\n                \"and MXNet record dependencies. Please install the required \"\n                \"optional dependencies before running this command.\"\n            ) from exc\n\n        tool = MaskRenderer()\n        tool.prepare(ctx_id=0, det_size=(128,128))\n        root_dir = self._input\n        path_imgrec = os.path.join(root_dir, 'train.rec')\n        path_imgidx = os.path.join(root_dir, 'train.idx')","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/python-package/insightface/commands/rec_add_mask_param.py#L21-L57","documentation":"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.","triggerScenarios":"Running 'insightface rec.addmaskparam ...' in an environment where 'import mxnet' raises ImportError.","commonSituations":"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.","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."],"exampleFix":"# before\ninsightface rec.addmaskparam --root ./ms1m  # ImportError: requires mxnet\n\n# after\npip install mxnet==1.9.1\ninsightface rec.addmaskparam --root ./ms1m","handlingStrategy":"validation","validationCode":"import importlib.util\nif importlib.util.find_spec('mxnet') is None:\n    raise SystemExit('rec.addmaskparam needs mxnet: pip install mxnet (py<=3.8)')","typeGuard":null,"tryCatchPattern":"try:\n    subprocess.run(['insightface', 'rec.addmaskparam', '--root', root], check=True)\nexcept subprocess.CalledProcessError:\n    # rerun inside a legacy mxnet-equipped container\n    ...","preventionTips":["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."],"tags":["mxnet","cli","optional-dependency","import"],"backgroundTag":"missing-required-dependency","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}