{"record":{"id":"8eebe9d89055073f","repo":"deepinsight/insightface","slug":"modelscope-is-not-available-you-have-two-options","errorCode":null,"errorMessage":"ModelScope is not available. You have two options:\n1. Install ModelScope: pip install modelscope\n2. Switch to OSS download mode by calling: inspireface.use_oss_download(True) before using InspireFace","messagePattern":"ModelScope is not available\\. You have two options:\n1\\. Install ModelScope: pip install modelscope\n2\\. Switch to OSS download mode by calling: inspireface\\.use_oss_download\\(True\\) before using InspireFace","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"cpp-package/inspireface/python/inspireface/modules/utils/resource.py","lineNumber":73,"sourceCode":"        \"\"\"\n        self.user_home = Path.home()\n        self.base_dir = self.user_home / '.inspireface'\n        self.models_dir = self.base_dir / 'models'\n        \n        # ModelScope configuration\n        self.use_modelscope = use_modelscope\n        self.modelscope_model_id = modelscope_model_id\n        self.modelscope_cache_dir = self.base_dir / 'ms'\n        \n        # Create directories\n        self.base_dir.mkdir(exist_ok=True)\n        self.models_dir.mkdir(exist_ok=True)\n        if self.use_modelscope:\n            self.modelscope_cache_dir.mkdir(exist_ok=True)\n            \n        # Check ModelScope availability\n        if self.use_modelscope and not MODELSCOPE_AVAILABLE:\n            raise ImportError(\n                \"ModelScope is not available. You have two options:\\n\"\n                \"1. Install ModelScope: pip install modelscope\\n\" \n                \"2. Switch to OSS download mode by calling: inspireface.use_oss_download(True) before using InspireFace\"\n            )\n        \n        # Model URLs\n        self._MODEL_LIST = {\n            \"Pikachu\": {\n                \"url\": \"https://inspireface-1259028827.cos.ap-singapore.myqcloud.com/inspireface_modelzoo/t4/Pikachu\",\n                \"filename\": \"Pikachu\",\n                \"md5\": \"5037ba1f49905b783a1c973d5d58b834a645922cc2814c8e3ca630a38dc24431\"\n            },\n            \"Megatron\": {\n                \"url\": \"https://inspireface-1259028827.cos.ap-singapore.myqcloud.com/inspireface_modelzoo/t4/Megatron\",\n                \"filename\": \"Megatron\",\n                \"md5\": \"709fddf024d9f34ec034d8ef79a4779e1543b867b05e428c1d4b766f69287050\"\n            },\n            \"Megatron_TRT\": {","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/python/inspireface/modules/utils/resource.py#L55-L91","documentation":"The resource manager's constructor raises ImportError when ModelScope download mode is selected (use_modelscope) but the modelscope package is not importable in the environment. InspireFace offers two model download backends and this guard fails fast instead of erroring mid-download.","triggerScenarios":"Constructing the resource manager / triggering first model access after opting into ModelScope mode without having installed the modelscope package (or in an env where its import failed).","commonSituations":"Following docs that recommend ModelScope for users near China; creating a fresh venv/conda env and copying code but not deps; modelscope installed but broken by a dependency conflict so the import fails.","solutions":["pip install modelscope","Or switch backend: call inspireface.use_oss_download(True) before any InspireFace usage to use the OSS downloader","Pin a working modelscope version if a dependency conflict broke the import (pip install 'modelscope>=1.9')"],"exampleFix":"# before\ninspireface.use_oss_download(False)  # ModelScope mode\nr = inspireface.Resource()  # ImportError\n# after (option 1)\n# pip install modelscope\n# after (option 2)\ninspireface.use_oss_download(True)\nr = inspireface.Resource()","handlingStrategy":"validation","validationCode":"try:\n    import modelscope  # noqa\nexcept ImportError:\n    import inspireface\n    inspireface.use_oss_download(True)","typeGuard":null,"tryCatchPattern":"try:\n    resource = Resource()\nexcept ImportError:\n    inspireface.use_oss_download(True)\n    resource = Resource()","preventionTips":["Add modelscope to requirements if you opt into ModelScope mode","Decide the download backend once at startup via use_oss_download"],"tags":["dependency","modelscope","download","optional-dependency"],"backgroundTag":"missing-optional-dependency","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}