Install & Compatibility
Where this runs
tested against v1.6.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.293s · 66.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.2s · import 0.281s · 67MB
65MB installed
● package 65MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
plugins
✓ import mkdocs.plugins
Commonly imported by plugin developers to define event handlers.
config
✓ from mkdocs import config
Used for programmatic access to MkDocs configuration, less common for typical users.
This quickstart demonstrates how to create a new MkDocs project and start its built-in development server. The `mkdocs new` command scaffolds a basic project structure with a `mkdocs.yml` configuration file and a `docs/` directory for your Markdown content. The `mkdocs serve` command then launches a local server with live-reloading for development.
import os
# Create a new MkDocs project
os.system("mkdocs new my-docs-project")
# Change into the project directory
os.chdir("my-docs-project")
# Start the development server (runs in the background for this example)
# In a real scenario, you'd run this from your terminal and visit http://127.0.0.1:8000
print("Run 'mkdocs serve' in your terminal in the 'my-docs-project' directory to preview your site.")
print("To open in browser automatically: 'mkdocs serve --open'")
mkdocs --version
Debug
Known issues
breakingThe `config.extra_javascript` option in `mkdocs.yml` changed behavior in version 1.5.0. It is no longer strictly a list of strings but can now contain mappings with keys like `type`, `async`, and `defer`. Plugins or themes directly manipulating this list must adapt.fixUpdate plugin/theme code to expect either strings or dictionary objects in `config.extra_javascript`. When reading values, cast to `str(value)` or check `isinstance` for dictionary attributes. Refer to the official documentation for the new structure.
affects: >=1.5.0
breakingIn version 1.6.0, the `exclude_docs` configuration option no longer provides 'drafts' functionality during `mkdocs serve`. Files specified under `exclude_docs` are now *always* excluded. A new option, `draft_docs`, was introduced for files that should appear during `serve` but not `build`.fixIf you relied on `exclude_docs` to treat certain files as drafts (visible during `serve` but not `build`), you must migrate them to the new `draft_docs` configuration option. Files listed in `exclude_docs` will now be completely absent from the served site as well.
affects: >=1.6.0
gotchaAs of version 1.5.0, `mkdocs serve` no longer exits immediately after detecting re-build errors (e.g., in configuration or plugins). Instead, it freezes the server, waiting for the user to fix the issue. Initial build errors, however, still cause an exit.fixWhen `mkdocs serve` appears unresponsive during development, check your console output for error messages. The server is likely paused, awaiting a fix to a detected problem in your documentation files or configuration. Correct the error, and the server should automatically resume.
affects: >=1.5.0
gotchaThe `site_url` configuration option is now effectively required for correct deployment, especially for features like sitemap generation and canonical URLs. Failing to set it, particularly when deploying to a subdirectory, can lead to broken links or incorrect metadata.fixAlways define `site_url` in your `mkdocs.yml`. Ensure it includes any subdirectories if your site is hosted at `https://example.com/foo/` rather than the root domain. Example: `site_url: https://example.com/foo/`.
affects: All versions (best practice), implicitly breaking for deploys >=1.5.0
Errors
Common errors & fixes
ERROR - Config value: 'theme'. Error: Unrecognised theme 'material'.
MkDocs cannot find the specified theme (e.g., 'material'), often because MkDocs and the theme were installed in different Python environments or via conflicting package managers (e.g., MkDocs via system, theme via pip).
fixEnsure you are using a virtual environment and install both MkDocs and the theme (e.g., `mkdocs-material`) using pip within that environment: `pip install mkdocs mkdocs-material`.
ERROR - Config value: 'pages'. Error: The configuration option 'pages' was removed from MkDocs. Use 'nav' instead. Aborted with 1 Configuration Errors!
The `pages` configuration setting in `mkdocs.yml` is deprecated and was replaced by `nav` in MkDocs 1.0.
fixUpdate your `mkdocs.yml` file to use `nav:` instead of `pages:` for defining your site's navigation structure.
WARNING - A reference to 'path/to/missing.md' is included in the 'nav' configuration, which is not found in the documentation files.
A Markdown file listed in the `nav` section of your `mkdocs.yml` configuration either does not exist, has an incorrect path relative to your `docs_dir`, or is excluded by other configuration settings.
fixVerify that the file specified in your `nav` configuration exists at the correct path relative to your `docs_dir` (typically `docs/`). Correct any typos or adjust the file path in `mkdocs.yml`.
ModuleNotFoundError: No module named 'pymdownx'
A Markdown extension (e.g., `pymdownx.highlight`, `pymdownx.superfences`) is enabled in your `mkdocs.yml` file, but the corresponding Python package for that extension (e.g., `pymdownx-details`, `pymdownx-highlight`) has not been installed.
fixInstall the missing Python package(s) using pip. For `pymdownx` extensions, you often need to install the `pymdown-extensions` package: `pip install pymdown-extensions`.
mkdocs: command not found
The `mkdocs` package is either not installed, or its executable location is not included in the system's PATH environment variable.
fixFirst, install MkDocs using `pip install mkdocs`. If already installed, ensure your Python installation's scripts directory (e.g., `C:\Python39\Scripts` or `~/.local/bin`) is in your system's PATH.
Upgrade
Version history
1.6.1latest on PyPI · released Aug 30, 2024
Audit
Dependencies
babeloptionalProvides internationalization (i18n) support, installed with `mkdocs[i18n]` extra.