Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Create a new MkDocs project, navigate into it, configure `mkdocs.yml` to use the Material theme, and then serve the documentation locally.
mkdocs new my-project
cd my-project
# Edit mkdocs.yml to apply the theme
with open('mkdocs.yml', 'w') as f:
f.write('site_name: My Documentation\n')
f.write('theme:\n')
f.write(' name: material\n')
mkdocs serve
mkdocs --version
Debug
Known issues
deprecatedMaterial for MkDocs is in maintenance mode. No new features will be added, and critical bug/security fixes are planned only until at least November 2026. Users should consider migration paths or be aware of the limited support window. The team is focusing on a new project, Zensical.fixPlan for migration to alternatives (like Zensical) or ensure current features meet long-term needs within the support window.
affects: >=9.7.0
breakingMaterial for MkDocs is incompatible with MkDocs 2.0. MkDocs 2.0 introduces backward-incompatible changes, including the removal/redesign of the plugin and theming systems. Users must pin their `mkdocs` dependency to `<2` to avoid breakage.fixEnsure `mkdocs` is explicitly pinned to a version less than 2 (e.g., `pip install mkdocs<2`).
affects: All versions with MkDocs 2.0+
deprecatedThe `projects` and `typeset` plugins were deprecated in version 9.7.0. They are included for compatibility but are considered architectural dead ends and are provided without ongoing support.fixAvoid using the `projects` and `typeset` plugins in new projects. For existing projects, be aware they will not receive updates or fixes.
affects: >=9.7.0
breakingUpgrading from 8.x to 9.x requires configuration changes for several features that became opt-in. This includes `content.code.copy`, `content.action.*`, and `navigation.footer`. Language codes like `kr` and `no` were also renamed to `ko` and `nb` respectively.fixReview the 'How to upgrade' guide in the official documentation and explicitly enable features that were previously implicit in your `mkdocs.yml` configuration. Update language codes if used.
affects: 9.x (from 8.x)
gotchaMaterial for MkDocs requires Python >=3.8. Using older Python versions can lead to dependency conflicts, such as `urllib3 v2.0` requiring OpenSSL 1.1.1+, which might not be met by older Python distributions.fixEnsure your Python environment is running version 3.8 or newer.
affects: <3.8
gotchaCLI commands provided by MkDocs (and by extension, Material for MkDocs) are shell commands and should be executed in a shell environment, not directly as Python code. Attempting to execute them as Python will result in a `SyntaxError`.fixEnsure `mkdocs` commands are run in a shell (e.g., directly from the command line, or via `subprocess.run` in a Python script), rather than being passed to the Python interpreter for direct execution.
affects: All versions
gotchaExecuting 'mkdocs' commands directly within a Python script (e.g., placing `mkdocs new my-project` as a line of code) will result in a SyntaxError. These commands must be run from a shell or invoked via Python's `subprocess` module.fixRun 'mkdocs' commands in a shell environment, or use `subprocess.run(['mkdocs', 'new', 'my-project'])` in Python scripts to execute them.
affects: All versions
Errors
Common errors & fixes
ERROR - Config value: 'theme'. Error: Unrecognised theme 'material'.
This error occurs when MkDocs cannot find the 'material' theme, often because MkDocs and Material for MkDocs were installed in different Python environments or via conflicting methods (e.g., system package manager vs. pip).
fixEnsure both MkDocs and Material for MkDocs are installed in the same Python environment, preferably within an activated virtual environment: `pip install mkdocs mkdocs-material`.
Could not install packages due to an EnvironmentError: [Errno 13] Permission denied:
This is a common Python installation error indicating that your user account lacks the necessary permissions to write to the default Python site-packages directory.
fixInstall packages within a Python virtual environment or use the `--user` flag to install into your user-specific site-packages directory: `pip install --user mkdocs-material`.
ModuleNotFoundError: No module named 'material.extensions'
This error typically signifies that the Python interpreter running MkDocs cannot locate the `material.extensions` module (often related to specific features like emoji extensions), which can happen due to environment conflicts, incorrect Python path, or incompatibility with the Python version.
fixEnsure you are running MkDocs from the correct virtual environment where `mkdocs-material` is installed (e.g., `python -m mkdocs serve`). Reinstalling `mkdocs-material` with `pip install mkdocs-material --force-reinstall` can also resolve path issues. For Python 3.12+, consider using a Python version known to be compatible (e.g., 3.10) if the issue persists.
WARNING - [timestamp] "GET /stylesheets/extra.css HTTP/1.1" code 404
This warning indicates that MkDocs' development server or the built site could not find the custom CSS file specified in your `mkdocs.yml` due to an incorrect path, improper YAML indentation, or the file not existing at the referenced location.
fixVerify the `extra_css` path in `mkdocs.yml` is correct and relative to your `docs` directory (e.g., `extra_css: - stylesheets/extra.css`), and ensure the `extra.css` file exists at that exact location (e.g., `docs/stylesheets/extra.css`). Also, check for correct YAML indentation.
ERROR - Config value: 'docs_dir': The path '...' isn't an existing directory.
The directory specified for `docs_dir` in your `mkdocs.yml` configuration does not exist or the path provided is incorrect relative to the `mkdocs.yml` file.
fixCorrect the `docs_dir` path in your `mkdocs.yml` to accurately point to the directory containing your Markdown source files, or create the specified directory if it's missing.
Upgrade
Version history
9.7.6latest on PyPI · released Mar 19, 2026
Audit
Dependencies
mkdocsrequiredMaterial for MkDocs is a theme built on top of MkDocs and requires it for functionality. It is explicitly incompatible with MkDocs 2.0 and requires MkDocs 1.x.