Install & Compatibility
Where this runs
tested against v1.2.3 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 34.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.2s · import 0.000s · 36MB
34MB installed
● package 34MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
✓ Not imported directly in Python code. Configured via mkdocs.yml.
Users enable and configure this plugin by adding it to the `plugins` section of their MkDocs configuration file, typically `mkdocs.yml`.
To enable `mkdocs-redirects`, add it to the `plugins` section of your `mkdocs.yml` file. Define redirect mappings using `redirect_maps`, where keys are old paths (relative to `docs_dir`) and values are new paths (can be internal relative, absolute, or external URLs).
# mkdocs.yml
site_name: My Awesome Docs
plugins:
- redirects:
redirect_maps:
'old-page.md': 'new-page.md'
'blog/legacy-post.md': '/blog/current-post/' # Absolute path within site
'external-link.md': 'https://example.com/new-resource'
'docs/old-section/chapter-1.md': '../new-section/chapter-1.md' # Relative to docs_dir
Debug
Known issues
breakingThe project maintainers are transitioning to a new organization, ProperDocs, and are encouraging the use of the `properdocs` executable over the traditional `mkdocs` executable. While `mkdocs-redirects` still functions with `mkdocs`, future versions and features may prioritize the ProperDocs ecosystem.fixFor long-term compatibility and to align with the project's evolving direction, consider exploring the ProperDocs ecosystem and its `properdocs` executable. Refer to the ProperDocs discussions for more details: `https://github.com/ProperDocs/properdocs/discussions/33`.
affects: 1.2.3 and onwards
breakingPython 3.9 support has been officially dropped.fixUpgrade your Python environment to 3.10 or newer. Python 3.14 is officially supported.
affects: 1.2.3 and onwards
gotchaPaths specified in `redirect_maps` are interpreted relative to your `docs_dir` (e.g., `docs/` by default) for the 'old path' keys. For 'new path' values, absolute paths (starting with `/`) are relative to the site root, and external URLs (starting with `http/https`) are handled directly. Relative paths in values (e.g., `../new-page.md`) are interpreted relative to the source file's location within `docs_dir`.fixCarefully verify redirect paths. For internal redirects, it is often safer and clearer to use absolute paths (e.g., `/new-page/`) for target URLs. Thoroughly test all redirects after configuration changes to prevent broken links.
affects: All versions
gotchaIf `use_directory_urls` is enabled in your `mkdocs.yml` (which is the default behavior), ensure your redirect target paths in `redirect_maps` reflect the directory-style URL structure (e.g., `new-page/` instead of `new-page.md`). Mixing styles can lead to unexpected redirect behavior.fixAlign your redirect target paths with the URL structure generated by MkDocs based on your `use_directory_urls` setting. If `use_directory_urls` is `true`, use directory-style paths for targets; if `false`, use `.html` suffixes.
affects: All versions
Upgrade
Version history
1.2.3latest on PyPI · released Mar 28, 2026
Audit
Dependencies
No dependency data recorded yet.