{"record":{"id":"2e0c162794cef27d","repo":"squidfunk/mkdocs-material","slug":"required-dependencies-of-social-plugin-not-found","errorCode":null,"errorMessage":"Required dependencies of \"social\" plugin not found:\n{import_errors}\n\n--> Install with: pip install \"mkdocs-material[imaging]\"","messagePattern":"Required dependencies of \"social\" plugin not found:\n(.+?)\n\n--> Install with: pip install \"mkdocs-material\\[imaging\\]\"","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/social/plugin.py","lineNumber":407,"sourceCode":"        # Check if file hash changed, so we need to re-generate the card - if\n        # the hash didn't change, we can just return the existing file\n        prev = self.manifest.get(file.url, \"\")\n        if hash == prev and os.path.isfile(file.abs_src_path):\n            return file\n\n        # Check if the required dependencies for rendering are available, which\n        # is, at the absolute minimum, the 'pillow' package, and raise an error\n        # to the caller, so he can decide what to do with the error. The caller\n        # can treat this as a warning or an error to abort the build.\n        if import_errors:\n            # docs = os.path.relpath(config.docs_dir)\n            # path = os.path.relpath(page.file.abs_src_path, docs)\n            # raise PluginError(\n            #     f\"Couldn't render card for '{path}' in '{docs}': install \"\n            #     f\"required dependencies – pip install 'mkdocs-material[imaging]'\"\n            # )\n            # @todo improve formatting of error handling\n            raise PluginError(\n                \"Required dependencies of \\\"social\\\" plugin not found:\\n\"\n                + str(\"\\n\".join(map(lambda x: \"- \" + x, import_errors)))\n                + \"\\n\\n\"\n                + \"--> Install with: pip install \\\"mkdocs-material[imaging]\\\"\"\n            )\n        if cairosvg_error:\n            # @todo improve formatting of error handling\n            raise PluginError(\n                \"\\\"cairosvg\\\" Python module is installed, but it crashed with:\\n\"\n                + cairosvg_error\n                + \"\\n\\n\"\n                + \"--> Check out the troubleshooting guide: https://t.ly/MfX6u\"\n            )\n\n        # Spawn concurrent jobs to render layers - we only need to render layers\n        # that we haven't already dispatched, reducing work by deduplication\n        for h, layer in layers.items():\n            sentinel = Future()","sourceCodeStart":389,"sourceCodeEnd":425,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/social/plugin.py#L389-L425","documentation":"The social plugin generates social cards at build time, which requires Pillow, Pillow-SIMD-compatible imaging support and CairoSVG. Before rendering, _generate checks the collected import errors for these optional dependencies; if any are missing it raises PluginError listing each missing module and the exact pip command to install them.","triggerScenarios":"Building with the social plugin enabled (cards generation on) while one or more of the required imaging packages fail to import — e.g. PIL, cairosvg or their native libraries — so import_errors is non-empty when _generate runs.","commonSituations":"Installing mkdocs-material without the [imaging] extra in CI; Linux images missing libcairo/pango native libs so cairosvg import fails; ARM/Alpine environments without prebuilt wheels; upgrading Python without reinstalling the extras.","solutions":["Run pip install \"mkdocs-material[imaging]\" in the environment that runs mkdocs","Read the '- module' lines in the error to see exactly which package failed, and install/repair that one (e.g. pip install cairosvg pillow)","On Linux install native libs first: apt-get install libcairo2 libpango-1.0-0 libpangocairo-1.0-0 (or the Alpine/macOS equivalents), then reinstall the extra","If card generation is not needed, disable the social plugin to skip the dependency requirement"],"exampleFix":"// before\npip install mkdocs-material\n// after\npip install \"mkdocs-material[imaging]\"","handlingStrategy":"validation","validationCode":"import importlib\nmissing = [m for m in (\"PIL\", \"cairosvg\") if importlib.util.find_spec(m) is None]\nif missing:\n    raise SystemExit(f\"Missing {missing} – pip install 'mkdocs-material[imaging]'\")","typeGuard":null,"tryCatchPattern":"try:\n    mkdocs build\nexcept SystemExit:\n    # install the packages listed with '- ' in the message, then rerun\n    pass","preventionTips":["Install with the extra everywhere: pip install \"mkdocs-material[imaging]\"","In Dockerfiles, apt-get install libcairo2 libpango-1.0-0 libpangocairo-1.0-0 before pip install","Cache a prebuilt CI image containing the imaging stack instead of installing per-job"],"tags":["python","missing-dependency","cairosvg","pillow","social-plugin","mkdocs"],"backgroundTag":"missing-optional-dependency","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}