{"record":{"id":"28fdad7d1a1ad4c3","repo":"squidfunk/mkdocs-material","slug":"couldn-t-optimize-image-path-in-docs-png","errorCode":null,"errorMessage":"Couldn't optimize image '{path}' in '{docs}': 'pngquant' not found. Make sure 'pngquant' is installed and in your path","messagePattern":"Couldn't optimize image '(.+?)' in '(.+?)': 'pngquant' not found\\. Make sure 'pngquant' is installed and in your path","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/optimize/plugin.py","lineNumber":319,"sourceCode":"        file.abs_src_path = path\n        file.src_path     = os.path.relpath(path, root)\n\n        # Return file to be copied from cache\n        return file\n\n    # Optimize PNG image - we first tried to use libimagequant, but encountered\n    # the occasional segmentation fault, which means it's probably not a good\n    # choice. Instead, we just rely on pngquant which seems much more stable.\n    def _optimize_image_png(self, file: File, path: str, config: MkDocsConfig):\n\n        # Check if the required dependencies for optimizing are available, which\n        # is, at the absolute minimum, the 'pngquant' binary, 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 not which(\"pngquant\"):\n            docs = os.path.relpath(config.docs_dir)\n            path = os.path.relpath(file.abs_src_path, docs)\n            raise PluginError(\n                f\"Couldn't optimize image '{path}' in '{docs}': 'pngquant' \"\n                f\"not found. Make sure 'pngquant' is installed and in your path\"\n            )\n\n        # Build command line arguments\n        args = [\"pngquant\",\n            \"--force\", \"--skip-if-larger\",\n            \"--output\", path,\n            \"--speed\", f\"{self.config.optimize_png_speed}\"\n        ]\n\n        # Add flag to remove optional metadata\n        if self.config.optimize_png_strip:\n            args.append(\"--strip\")\n\n        # Set input file and run, then check if pngquant actually wrote a file,\n        # as we instruct it not to if the size of the optimized file is larger.\n        # This can happen if files are already compressed and optimized by","sourceCodeStart":301,"sourceCodeEnd":337,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/optimize/plugin.py#L301-L337","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Install pngquant: `apt-get install pngquant` (Debian/Ubuntu), `brew install pngquant` (macOS), or the equivalent for your OS","Ensure the binary is on the PATH of the environment running mkdocs (`which pngquant` to verify)","In CI, add an install step for pngquant before running mkdocs","If optimization isn't needed, disable PNG optimization in the optimize plugin config"],"exampleFix":"# before (CI)\n- run: mkdocs build\n\n// after\n- run: sudo apt-get update && sudo apt-get install -y pngquant\n- run: mkdocs build","handlingStrategy":"fallback","validationCode":"import shutil\nassert shutil.which('pngquant'), \"pngquant not installed or not on PATH\"\n","typeGuard":null,"tryCatchPattern":"try:\n    mkdocs.commands.build(config)\nexcept PluginError as e:\n    if \"pngquant\" in str(e):\n        log.warning(\"Skipping image optimization; install pngquant for optimization\")\n    else:\n        raise\n","preventionTips":["Install pngquant in every build environment, including CI images and Dockerfiles","Verify with `which pngquant` in the same shell/venv that runs mkdocs","Add a setup step installing pngquant before `mkdocs build` in CI","Alternatively disable PNG optimization in the optimize plugin config if images need not be compressed"],"tags":["mkdocs","optimize-plugin","missing-binary","pngquant","environment"],"backgroundTag":"missing-binary-dependency","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}