squidfunk/mkdocs-material · error · PluginError

Required dependencies of "social" plugin not found: {import_

Error message

Required dependencies of "social" plugin not found:
{import_errors}

--> Install with: pip install "mkdocs-material[imaging]"

What it means

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.

Source

Thrown at src/plugins/social/plugin.py:407

        # Check if file hash changed, so we need to re-generate the card - if
        # the hash didn't change, we can just return the existing file
        prev = self.manifest.get(file.url, "")
        if hash == prev and os.path.isfile(file.abs_src_path):
            return file

        # Check if the required dependencies for rendering are available, which
        # is, at the absolute minimum, the 'pillow' package, and raise an error
        # to the caller, so he can decide what to do with the error. The caller
        # can treat this as a warning or an error to abort the build.
        if import_errors:
            # docs = os.path.relpath(config.docs_dir)
            # path = os.path.relpath(page.file.abs_src_path, docs)
            # raise PluginError(
            #     f"Couldn't render card for '{path}' in '{docs}': install "
            #     f"required dependencies – pip install 'mkdocs-material[imaging]'"
            # )
            # @todo improve formatting of error handling
            raise PluginError(
                "Required dependencies of \"social\" plugin not found:\n"
                + str("\n".join(map(lambda x: "- " + x, import_errors)))
                + "\n\n"
                + "--> Install with: pip install \"mkdocs-material[imaging]\""
            )
        if cairosvg_error:
            # @todo improve formatting of error handling
            raise PluginError(
                "\"cairosvg\" Python module is installed, but it crashed with:\n"
                + cairosvg_error
                + "\n\n"
                + "--> Check out the troubleshooting guide: https://t.ly/MfX6u"
            )

        # Spawn concurrent jobs to render layers - we only need to render layers
        # that we haven't already dispatched, reducing work by deduplication
        for h, layer in layers.items():
            sentinel = Future()

View on GitHub (pinned to e2136532f4)

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

Example fix

// before
pip install mkdocs-material
// after
pip install "mkdocs-material[imaging]"

Defensive patterns

Strategy: validation

Validate before calling

import importlib
missing = [m for m in ("PIL", "cairosvg") if importlib.util.find_spec(m) is None]
if missing:
    raise SystemExit(f"Missing {missing} – pip install 'mkdocs-material[imaging]'")

Try / catch

try:
    mkdocs build
except SystemExit:
    # install the packages listed with '- ' in the message, then rerun
    pass

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

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 squidfunk/mkdocs-material@e2136532f4 (2026-08-29). Data as JSON: /api/errors/2e0c162794cef27d. Report an issue: GitHub.