squidfunk/mkdocs-material · error · PluginError

Couldn't optimize image '{path}' in '{docs}': install requir

Error message

Couldn't optimize image '{path}' in '{docs}': install required dependencies – pip install 'mkdocs-material[imaging]'

What it means

The optimize plugin optimizes JPEG/PNG/SVG assets during the build. Optimization requires Pillow (and other imaging libraries); before processing a JPG the plugin checks whether the PIL 'Image' module is importable via _supports("Image"). If not, it raises PluginError naming the file and docs dir, telling the author to install the imaging extras. The caller can downgrade this to a warning or abort the build.

Source

Thrown at src/plugins/optimize/plugin.py:353

        # Set input file and run, then check if pngquant actually wrote a file,
        # as we instruct it not to if the size of the optimized file is larger.
        # This can happen if files are already compressed and optimized by
        # the author. In that case, just copy the original file.
        subprocess.run([*args, file.abs_src_path])
        if not os.path.isfile(path):
            utils.copy_file(file.abs_src_path, path)

    # Optimize JPG image
    def _optimize_image_jpg(self, file: File, path: str, config: MkDocsConfig):

        # Check if the required dependencies for optimizing 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 not _supports("Image"):
            docs = os.path.relpath(config.docs_dir)
            path = os.path.relpath(file.abs_src_path, docs)
            raise PluginError(
                f"Couldn't optimize image '{path}' in '{docs}': install "
                f"required dependencies – pip install 'mkdocs-material[imaging]'"
            )

        # Open and save optimized image
        image = Image.open(file.abs_src_path)
        image.save(path, "jpeg",
            quality     = self.config.optimize_jpg_quality,
            progressive = self.config.optimize_jpg_progressive
        )

# -----------------------------------------------------------------------------
# Helper functions
# -----------------------------------------------------------------------------

# Check for presence of optional imports
@functools.lru_cache(maxsize = None)
def _supports(name: str):

View on GitHub (pinned to e2136532f4)

Solutions

1. Install the imaging extras: pip install 'mkdocs-material[imaging]'
2. Verify the active interpreter has Pillow: python -c 'import PIL; print(PIL.__version__)' in the same venv used by mkdocs
3. If Pillow cannot be installed, disable the optimize plugin or remove the offending images so the build does not attempt optimization

Example fix

// before (no imaging extra)
pip install mkdocs-material
// after
pip install 'mkdocs-material[imaging]'

try:
    from PIL import Image
except ImportError:
    raise SystemExit("Pillow missing – run: pip install 'mkdocs-material[imaging]'")

try:
    mkdocs build
except SystemExit:
    pass  # PluginError surfaces as build abort; fix deps and rerun

When it happens

Trigger: Building docs with the optimize plugin enabled while the 'Pillow' package is not installed (or its import fails), and the build encounters a JPG image in the docs directory that goes through _optimize_image -> _optimize_image_jpg.

Common situations: Fresh CI containers or virtualenvs where only mkdocs-material was installed without the [imaging] extra; deployment images stripped of Pillow; a Python upgrade wiping site-packages; contributors running mkdocs serve locally without the extra.

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

• Required dependencies of "social" plugin not found: {import_
• Relative path processor not registered
• Error reading filter configuration in '{key}': {e}
• Unknown shortcode: {type}
• Unknown type: {type}

AI-assisted analysis of squidfunk/mkdocs-material@e2136532f4 (2026-08-29). Data as JSON: /api/errors/89ad0e7645bb0960. Report an issue: GitHub.