mkdocstrings-python-legacy

What it is and what it does

mkdocstrings-python-legacy is a plugin handler that integrates Python API documentation generation into MkDocs sites. It uses pytkdocs to extract object trees and docstrings from Python source code, then renders them as Markdown with support for Google, Numpydoc, and Sphinx docstring styles. It displays type annotations, recursive module documentation, documented attributes, and source code listings, with each object appearing as a navigable heading in the table of contents.

This is a legacy package—the project recommends using the newer mkdocstrings-python handler instead. It remains available for projects with existing configurations or specific compatibility needs. The package depends on mkdocstrings, mkdocs-autorefs, and pytkdocs, and supports Python 3.9 through 3.14.

Use it for:

• Maintaining existing MkDocs documentation sites that were built with the legacy Python handler and do not require migration.
• Generating API reference documentation from Python docstrings without manually writing Markdown files.
• Displaying type hints and function signatures alongside docstrings in auto-generated documentation.
• Converting Google-style or Numpydoc-style docstrings into admonitions and formatted Markdown.
• Building a searchable table of contents for Python module and class documentation in Material theme sites.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A legacy Python documentation handler for mkdocstrings that extracts and renders API documentation from Python source code, docstrings, and type annotations into MkDocs sites.

Yes, if you are maintaining an existing MkDocs site already using this handler and do not need to migrate. No, if you are starting a new documentation project—use the recommended newer mkdocstrings-python handler instead. The legacy package is stable and permissively licensed, but aging (449 days since last release) and explicitly superseded; install only for backward compatibility.

Install

mkdocstrings-python-legacy on PyPI

pip install mkdocstrings-python-legacy

uv add mkdocstrings-python-legacy

poetry add mkdocstrings-python-legacy

Installing mkdocstrings-python-legacy

Before you install

Low install friction with a pure-Python wheel. Maintenance is aging—last release was 449 days ago and the repository has only 3 stars—but the codebase remains active (last commit 2026-01-13) and the package is explicitly marked as legacy in favor of a newer handler.

License in practice

ISC license is permissive and poses no restrictions on use, modification, or distribution in commercial or private projects.

Quickstart

# Install via mkdocstrings extra or directly
pip install mkdocstrings[python-legacy]
# or
pip install mkdocstrings-python-legacy

# In mkdocs.yml, configure the handler
plugins:
  - mkdocstrings:
      handlers:
        python:
          handler: python-legacy

Requires mkdocstrings >=0.18 and Python >=3.9; intended as a fallback for projects already using the legacy handler.

Verify before relying

• Whether the legacy handler remains compatible with the latest mkdocstrings releases and MkDocs Material theme.
• Performance and feature parity compared to the recommended newer mkdocstrings-python handler.
• Active maintenance timeline and whether critical bug fixes are still applied.

Package facts

Evidence: mkdocstrings_python_legacy-0.2.7-py3-none-any.whl

Tags

More Software Development packages