Install & Compatibility
Where this runs
tested against v1.0.6 · 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.650s · 40.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.6s · import 0.606s · 42MB
39MB installed
● package 39MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MkdocstringsPlugin
✓ from mkdocstrings import MkdocstringsPlugin
✗ from mkdocstrings.plugin import MkdocstringsPlugin
To quickly get started, install mkdocstrings with the Python handler. Create a `mkdocs.yml` file, add the `mkdocstrings` plugin, and configure the Python handler to point to your source code directory (e.g., `src`). Then, in your Markdown files, use the `:::` syntax to reference your Python objects. This example shows how to document a function `greet` from `src/my_module.py`.
# mkdocs.yml
site_name: My Awesome Project
theme: material
plugins:
- mkdocstrings: # Enable the mkdocstrings plugin
handlers:
python:
paths: [src] # Tell the Python handler where to find your code
# src/my_module.py
def greet(name: str) -> str:
"""
Greets a person by their name.
Parameters:
name: The name of the person to greet.
Returns:
A personalized greeting string.
"""
return f"Hello, {name}!"
# docs/index.md
# Welcome
This is the main documentation page.
## API Reference
::: src.my_module.greet
options:
show_source: false
Debug
Known issues
breakingVersion 1.0.0 introduced significant breaking changes to the `BaseHandler` API. If you have custom handlers or extend `mkdocstrings` programmatically, your code will likely break.fixReview the changelog for 1.0.0. Key changes include removal of `BaseHandler.name`, `BaseHandler.domain`, `BaseHandler.fallback_config`, and changes to `BaseHandler.__init__` parameters. Update your custom handler implementations accordingly.
affects: < 1.0.0 (when upgrading to 1.0.0+)
deprecatedImporting public objects directly from submodules (e.g., `mkdocstrings.handlers.python.PythonHandler`) was deprecated in 0.28.3 and will raise errors in v1.x. Public objects should now be imported from the top-level `mkdocstrings` module.fixConsult the official documentation for the canonical import paths of public objects. Where possible, import directly from `mkdocstrings`.
affects: 0.28.3 - 0.x (when upgrading to 1.x)
gotchamkdocstrings requires a language-specific 'handler' to actually parse and document code (e.g., for Python, `mkdocstrings-python`). Installing `mkdocstrings` alone is often not enough.fixInstall the appropriate handler for your language. For Python, use `pip install "mkdocstrings[python]"` or `pip install mkdocstrings-python`.
affects: All versions
gotchaIncorrect or missing plugin configuration in `mkdocs.yml` is a common source of errors. Users often forget to list `mkdocstrings` under the `plugins:` section or misconfigure handler-specific options like `paths`.fixEnsure `mkdocstrings` is correctly listed under `plugins:` in your `mkdocs.yml`. Verify that handler-specific options (e.g., `python.paths`) point to the correct directories containing your source code.
affects: All versions
gotchaWhen using `mkdocstrings` with `mkdocs-autorefs`, the order of plugins in `mkdocs.yml` matters. `mkdocstrings` should generally be listed *before* `mkdocs-autorefs` to ensure that references are properly resolved.fixConfigure your `mkdocs.yml` `plugins` section as follows: `plugins: - mkdocstrings - mkdocs-autorefs`.
affects: All versions (when using both plugins)
gotchaAttempting to run an `mkdocs.yml` configuration file directly as a Python script will result in a `SyntaxError`, as Python cannot interpret YAML syntax. The `mkdocs.yml` file is meant to be processed by the `mkdocs` command-line tool, not executed directly.fixDo not run `mkdocs.yml` directly. Instead, use the `mkdocs` command-line tool (e.g., `mkdocs build`, `mkdocs serve`) in the directory containing `mkdocs.yml`.
affects: All versions
gotchaMkDocs configuration files (`mkdocs.yml`) are YAML files and should be processed by the `mkdocs` command-line tool, not executed directly as Python scripts. Attempting to execute `mkdocs.yml` as a Python script will result in a `SyntaxError`.fixEnsure you are using the `mkdocs` command (e.g., `mkdocs build` or `mkdocs serve`) to process your project, and that your `mkdocs.yml` file is correctly placed in your project root or specified using the `-f` option.
affects: All versions
Upgrade
Version history
1.0.6latest on PyPI · released Jul 11, 2026
Audit
Dependencies
mkdocsrequiredCore dependency; mkdocstrings is an MkDocs plugin. Requires MkDocs >= 1.6 since mkdocstrings 0.29.0.
mkdocstrings-pythonoptionalProvides Python language support; installed via `[python]` extra.
mkdocs-autorefsoptionalOptional dependency for advanced cross-referencing capabilities. Required mkdocs-autorefs >= 1.4 since mkdocstrings 0.28.2.