{"record":{"id":"89ad0e7645bb0960","repo":"squidfunk/mkdocs-material","slug":"couldn-t-optimize-image-path-in-docs-inst","errorCode":null,"errorMessage":"Couldn't optimize image '{path}' in '{docs}': install required dependencies – pip install 'mkdocs-material[imaging]'","messagePattern":"Couldn't optimize image '(.+?)' in '(.+?)': install required dependencies – pip install 'mkdocs-material\\[imaging\\]'","errorType":"exception","errorClass":"PluginError","httpStatus":null,"severity":"error","filePath":"src/plugins/optimize/plugin.py","lineNumber":353,"sourceCode":"        # 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\n        # the author. In that case, just copy the original file.\n        subprocess.run([*args, file.abs_src_path])\n        if not os.path.isfile(path):\n            utils.copy_file(file.abs_src_path, path)\n\n    # Optimize JPG image\n    def _optimize_image_jpg(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 '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 not _supports(\"Image\"):\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}': install \"\n                f\"required dependencies – pip install 'mkdocs-material[imaging]'\"\n            )\n\n        # Open and save optimized image\n        image = Image.open(file.abs_src_path)\n        image.save(path, \"jpeg\",\n            quality     = self.config.optimize_jpg_quality,\n            progressive = self.config.optimize_jpg_progressive\n        )\n\n# -----------------------------------------------------------------------------\n# Helper functions\n# -----------------------------------------------------------------------------\n\n# Check for presence of optional imports\n@functools.lru_cache(maxsize = None)\ndef _supports(name: str):","sourceCodeStart":335,"sourceCodeEnd":371,"githubUrl":"https://github.com/squidfunk/mkdocs-material/blob/e2136532f40aed98af1f6497c0cc6a3cff9f759b/src/plugins/optimize/plugin.py#L335-L371","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the imaging extras: pip install 'mkdocs-material[imaging]'","Verify the active interpreter has Pillow: python -c 'import PIL; print(PIL.__version__)' in the same venv used by mkdocs","If Pillow cannot be installed, disable the optimize plugin or remove the offending images so the build does not attempt optimization"],"exampleFix":"// before (no imaging extra)\npip install mkdocs-material\n// after\npip install 'mkdocs-material[imaging]'","handlingStrategy":"validation","validationCode":"try:\n    from PIL import Image\nexcept ImportError:\n    raise SystemExit(\"Pillow missing – run: pip install 'mkdocs-material[imaging]'\")","typeGuard":null,"tryCatchPattern":"try:\n    mkdocs build\nexcept SystemExit:\n    pass  # PluginError surfaces as build abort; fix deps and rerun","preventionTips":["Pin mkdocs-material[imaging] in requirements.txt so the extra is always installed","In CI, run python -c \"import PIL\" as a pre-build sanity step","Use a locked environment (uv/pip-tools) so imaging deps never drop out on upgrades"],"tags":["python","missing-dependency","pillow","mkdocs","image-optimization"],"backgroundTag":"missing-optional-dependency","analyzedSha":"e2136532f40aed98af1f6497c0cc6a3cff9f759b","analyzedAt":"2026-08-29T11:20:04.299Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}