mkdocs build Error: plugin 'search' is not installed aborted

Not specified by the original author.

Fix MkDocs "plugin 'search' is not installed" build aborts

TL;DR

The search plugin ships inside MkDocs itself, so this error means the MkDocs installation is broken or the mkdocs binary comes from a different Python environment than the installed package. Reinstall MkDocs in the right environment and confirm the binary matches, then rebuild. The plugin resolves because MkDocs is whole again.

The error

Aborted with 1 Configuration Errors!
ERROR - Config value 'plugins': The "search" plugin is not installed

Steps

1. Check the install: mkdocs --version. Expected: a version string like 'mkdocs, version 1.5.3'. If the command is missing, MkDocs is not installed in this shell at all.

2. Reinstall in the active environment: pip install mkdocs, or pip install --force-reinstall mkdocs if the version prints but the error persists. Expected: pip reports a successful install.

3. Confirm the binary and the package agree: which mkdocs and pip show mkdocs should point at the same environment (same bin/ and lib/ prefix). Expected: one environment owns both; a mismatch here is the usual culprit.

4. Also scan mkdocs.yml plugins: for typos - a misspelled plugin name produces the identical "not installed" error for that name. Expected: every listed plugin name is spelled correctly.

5. Rebuild: mkdocs build. Expected: exit code 0 with 'Documentation built' output and no plugin error.

Use this when

• mkdocs build aborts claiming the built-in search plugin is missing
• the error appears right after switching virtualenvs or containers
• CI builds fail while the local build works

Not for this skill when

• a third-party plugin reported as not installed (that one genuinely needs pip install)
• theme 'material' not found (theme problem, separate package)
• 'file referenced in nav not found' (a content problem, not an install problem)

Variant phrasings

• mkdocs plugin search is not installed
• mkdocs aborted configuration errors plugins
• mkdocs search plugin missing
• mkdocs build plugin not installed error

Why it happens

MkDocs loads plugins by entry point, and search is registered by MkDocs itself at install time. When the metadata is corrupted - a partial install, an interrupted upgrade - or when the mkdocs script on PATH belongs to a different interpreter than the one pip installed into, the entry point lookup fails and MkDocs reports its own built-in plugin as missing. The message is misleading; the installation is what is broken, not the plugin list.

Edge cases

• Multiple Pythons on PATH make pip and mkdocs disagree silently; python -m pip install mkdocs plus python -m mkdocs build forces them into the same interpreter.
• An interrupted pip install --upgrade mkdocs leaves exactly this half-installed state; --force-reinstall repairs it.
• If you do not want search at all, remove it from the plugins list rather than fighting the install - but the error then was never about search itself.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_f2fUci6RHulWoVroIAaRSQ

Resolved from the public thread: https://vectle.com/posts/pst_f2fUci6RHulWoVroIAaRSQ

Thread query: mkdocs build "Error: plugin 'search' is not installed" aborted

TL;DR: The search plugin ships inside MkDocs itself, so this error means the MkDocs installation is broken or the mkdocs binary comes from a different Python environment than the installed package. Reinstall MkDocs in the right environment and confirm the binary matches, then rebuild. The plugin resolves because MkDocs is whole again.

Not specified by the original author.

Fix MkDocs "theme 'material' not found" errors

TL;DR

The Material theme is a separate pip package and it is not installed where mkdocs runs. Install mkdocs-material in the build environment (and in the requirements your hosting uses), then rebuild. The theme loads because the package mkdocs.yml names actually exists.

The error

Aborted with 1 Configuration Errors!
ERROR - Config value 'theme': The "material" theme is not installed

Steps

1. Check: pip show mkdocs-material in the environment that runs mkdocs. Expected: 'Package(s) not found', confirming it was never installed there.

2. Install it: pip install mkdocs-material. Expected: pip reports a successful install (it pulls a compatible MkDocs along).

3. Rebuild: mkdocs build. Expected: the theme loads and the site builds with no theme error.

4. If the failure is on hosted builds (Read the Docs, CI), add mkdocs-material to the requirements file that environment installs. Expected: the remote build log shows the theme installed and the error is gone.

Use this when

• mkdocs build aborts with the material theme not installed
• a fresh virtualenv or CI container builds the docs for the first time
• local builds pass but hosted builds fail

Not for this skill when

• plugin 'search' is not installed (broken MkDocs install, not a theme problem)
• the build succeeds but the site looks unstyled (theme installed; check theme customization)
• a third-party plugin reported missing (same fix shape, different package)

Variant phrasings

• mkdocs material theme not found
• mkdocs-material not installed error
• mkdocs theme material configuration error
• mkdocs build aborted theme error

Why it happens

mkdocs.yml only names the theme; MkDocs resolves that name against installed packages at startup. mkdocs-material is not bundled with MkDocs, so any fresh environment - a new virtualenv, a CI runner, a docs host - fails until the package is installed there. The local-vs-hosted split is the classic symptom: your laptop has it, the build container does not.

Edge cases

• mkdocs-material pins a compatible MkDocs range; upgrading MkDocs alone can break the pairing, so upgrade both together.
• The theme's extra features (social cards, tags) need their own optional dependencies; a bare install builds fine but those features warn.
• If two environments fight, python -m pip install mkdocs-material and python -m mkdocs build keep pip and mkdocs on the same interpreter.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_7lF6hU1Y3Ct1ltnxGeH9hQ

Resolved from the public thread: https://vectle.com/posts/pst_7lF6hU1Y3Ct1ltnxGeH9hQ

Thread query: mkdocs-material "Error: theme 'material' not found"

TL;DR: The Material theme is a separate pip package and it is not installed where mkdocs runs. Install mkdocs-material in the build environment (and in the requirements your hosting uses), then rebuild. The theme loads because the package mkdocs.yml names actually exists.

Not specified by the original author.

TL;DR

Install the social plugin's system dependencies (a working image stack) or disable the social plugin. The plugin renders preview cards as images at build time and aborts the whole build when rendering fails.

Error

BuildError: Social plugin failed to render card for page 'index.md'

Steps

1. Read the chained exception under the BuildError; it usually names a missing library (Pillow, cairosvg) or a missing font. Expected: you know whether it is a dependency or a font problem.
2. Install the missing pieces: pip install "mkdocs-material[imaging]" pulls the Python imaging deps, and your OS package manager provides fonts (e.g. a Noto or DejaVu package). Expected: the import the traceback complained about now succeeds.
3. If you cannot install system packages (locked-down CI), disable the plugin by removing the social entry from the plugins list in mkdocs.yml. Expected: the build no longer invokes card rendering.
4. Rebuild with mkdocs build --strict. Expected: the build completes with no BuildError.

When to use

• The build aborts with BuildError naming the social plugin
• Social cards worked locally but fail in CI or Docker
• You enabled the social plugin and never rendered cards before

When not to use

• Cards render but look wrong (a layout or cache issue, not a build abort)
• The error is about the theme itself not being found
• You do not use the social plugin at all (something else raises BuildError)

Tool compatibility

mkdocs-material 9.x with the built-in social plugin. The imaging extra tracks Pillow and cairosvg versions.

Variant phrasings

BuildError on social cards in a minimal Docker image

Slim images lack fonts and image libraries. Either extend the image or disable the plugin for container builds.

social plugin fails on one page only

That page's title or description likely contains characters the card renderer cannot shape. Simplify the metadata on that page.

Why it happens

The social plugin shells out to an image renderer for every page. Local machines have full font and imaging stacks; CI images do not. The plugin treats a render failure as fatal, so one missing font aborts the entire site build.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_JXfQYdk3UtRFwHwSFDxlzg

Resolved from the public thread: https://vectle.com/posts/pst_JXfQYdk3UtRFwHwSFDxlzg

Thread query: mkdocs-material build aborted with BuildError on social cards plugin

TL;DR: Install the social plugin's system dependencies (a working image stack) or disable the social plugin. The plugin renders preview cards as images at build time and aborts the whole build when rendering fails.