squidfunk/mkdocs-material · error · PluginError

Couldn't optimize image '{path}' in '{docs}': 'pngquant' not

Error message

Couldn't optimize image '{path}' in '{docs}': 'pngquant' not found. Make sure 'pngquant' is installed and in your path

What it means

The optimize plugin compresses PNG images with the external `pngquant` binary. Before optimizing, `_optimize_image_png` checks for the binary on PATH with `shutil.which`; if it is absent, the build raises this PluginError telling the user to install pngquant. Depending on configuration this may be treated as a warning or abort the build.

Source

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

        file.abs_src_path = path
        file.src_path     = os.path.relpath(path, root)

        # Return file to be copied from cache
        return file

    # Optimize PNG image - we first tried to use libimagequant, but encountered
    # the occasional segmentation fault, which means it's probably not a good
    # choice. Instead, we just rely on pngquant which seems much more stable.
    def _optimize_image_png(self, file: File, path: str, config: MkDocsConfig):

        # Check if the required dependencies for optimizing are available, which
        # is, at the absolute minimum, the 'pngquant' binary, 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 which("pngquant"):
            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}': 'pngquant' "
                f"not found. Make sure 'pngquant' is installed and in your path"
            )

        # Build command line arguments
        args = ["pngquant",
            "--force", "--skip-if-larger",
            "--output", path,
            "--speed", f"{self.config.optimize_png_speed}"
        ]

        # Add flag to remove optional metadata
        if self.config.optimize_png_strip:
            args.append("--strip")

        # 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

View on GitHub (pinned to e2136532f4)

Solutions

1. Install pngquant: `apt-get install pngquant` (Debian/Ubuntu), `brew install pngquant` (macOS), or the equivalent for your OS
2. Ensure the binary is on the PATH of the environment running mkdocs (`which pngquant` to verify)
3. In CI, add an install step for pngquant before running mkdocs
4. If optimization isn't needed, disable PNG optimization in the optimize plugin config

Example fix

# before (CI)
- run: mkdocs build

// after
- run: sudo apt-get update && sudo apt-get install -y pngquant
- run: mkdocs build

import shutil
assert shutil.which('pngquant'), "pngquant not installed or not on PATH"

try:
    mkdocs.commands.build(config)
except PluginError as e:
    if "pngquant" in str(e):
        log.warning("Skipping image optimization; install pngquant for optimization")
    else:
        raise

When it happens

Trigger: The build processes at least one PNG image while `pngquant` is not installed or not on the PATH of the environment running mkdocs (CI containers, virtualenvs without system deps, Windows installs).

Common situations: CI pipeline images lacking pngquant (`apt install pngquant` not run); using Docker images without the binary; installing mkdocs in a venv but the system utility missing; macOS/Windows without the tool in PATH.

Related errors

• "cairosvg" Python module is installed, but it crashed with:
• 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/28fdad7d1a1ad4c3. Report an issue: GitHub.