{"id":1050,"library":"pymdown-extensions","title":"Pymdown Extensions","description":"Pymdown Extensions is an extension pack for Python Markdown, offering a comprehensive collection of features to enhance Markdown rendering. It provides over 30 extensions for capabilities such as enhanced code blocks with highlighting, content tabs, emoji support, and mathematical notation. Currently at version 10.21.2, the library is actively developed with a consistent release cadence.","status":"active","version":"10.21.2","language":"python","source_language":"en","source_url":"https://github.com/facelessuser/pymdown-extensions","tags":["markdown","extensions","text-processing","documentation"],"install":[{"cmd":"pip install pymdown-extensions","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for parsing Markdown.","package":"markdown","optional":false},{"reason":"Required for the 'highlight' extension's syntax highlighting capabilities.","package":"Pygments","optional":true}],"imports":[{"note":"Pymdown Extensions are loaded by their module name (e.g., 'pymdownx.superfences') into the `extensions` list of `markdown.Markdown`.","symbol":"markdown.Markdown","correct":"import markdown\nhtml = markdown.Markdown(extensions=['pymdownx.superfences', 'pymdownx.highlight']).convert(md_text)"}],"quickstart":{"code":"import markdown\n\nmd_text = '''\n# Hello Pymdown!\n\nThis is a simple markdown with `inline code`.\n\n```python\n# SuperFences and Highlight example\ndef greet(name):\n    print(f\"Hello, {name}!\")\n\ngreet(\"World\")\n```\n''')\n\n# To use Pymdown Extensions, pass their names (prefixed with 'pymdownx.')\n# to the 'extensions' argument of markdown.Markdown.\n# 'superfences' allows nested code blocks, and 'highlight' provides syntax highlighting.\nhtml = markdown.Markdown(\n    extensions=[\n        'pymdownx.superfences',\n        'pymdownx.highlight',\n        'pymdownx.emoji'\n    ]\n).convert(md_text)\n\nprint(html)","lang":"python","description":"Initialize a Markdown converter with `pymdown-extensions` by listing their names (e.g., `pymdownx.superfences`, `pymdownx.highlight`) in the `extensions` argument. The example demonstrates basic Markdown conversion with code block highlighting and emoji support."},"warnings":[{"fix":"Update Critic extension configuration to use `mode: accept` or `mode: reject` instead of `view`.","message":"The 'Critic' extension's `view` mode was deprecated in version 10.18 and is slated for future removal. Users should explicitly set `mode` to either `accept` or `reject` to avoid warnings and ensure future compatibility.","severity":"breaking","affected_versions":">=10.18"},{"fix":"Upgrade to version 10.21.2 or later. Ensure a string is always provided for `filename` if custom titles are used.","message":"The 'Highlight' extension, prior to version 10.21.2, had issues handling `None` as a filename for code block titles, leading to potential errors with newer Pygments versions.","severity":"gotcha","affected_versions":"<10.21.2"},{"fix":"Review documentation for the 'Quotes' extension, especially regarding its grouping behavior, and adjust content or expectations if coming from Python Markdown's default blockquote parsing.","message":"The new 'Quotes' extension (introduced in 10.20) handles blockquote grouping differently than Python Markdown's default, following a more modern parsing approach. This may change expected behavior if migrating from the default blockquote parsing.","severity":"gotcha","affected_versions":">=10.20"},{"fix":"Upgrade to version 10.19.1 or later to resolve the nested math parsing issue.","message":"A bug in 'Arithmatex' prior to 10.19.1 could cause incorrect parsing of block math (`$$`) when used inline within a paragraph, resulting in nested math parsing issues.","severity":"gotcha","affected_versions":"<10.19.1"},{"fix":"Correct the Python syntax error in `/script.py` (specifically, the unmatched parenthesis on line 15) to allow the test to proceed and evaluate the library functionality.","message":"The test script (`/script.py`) encountered a Python `SyntaxError: unmatched ')'`, indicating an issue with the script's syntax rather than a direct library behavior. This prevents the library from being effectively tested.","severity":"breaking","affected_versions":"N/A"}],"env_vars":null,"last_verified":"2026-05-12T23:08:50.362Z","next_check":"2026-06-29T00:00:00.000Z","problems":[{"fix":"Ensure `pymdown-extensions` is installed (`pip install pymdown-extensions`). Double-check the extension name for typos in `mkdocs.yml`, confirm correct YAML indentation for any extension options, and verify that all necessary sub-dependencies (like `Pygments` for `highlight`) are met. Sometimes, a `pip install pymdown-extensions --force` followed by `mkdocs build --clean` can resolve caching issues.","cause":"This error typically occurs when an extension listed in the MkDocs configuration (`mkdocs.yml`) is either not installed, misspelled, or has an incorrect YAML configuration (e.g., improper indentation for options).","error":"Error: Failed loading extension \"pymdownx.<extension_name>\""},{"fix":"Install the package using pip: `pip install pymdown-extensions`. If it's already installed, ensure you're running your application in the correct Python environment where the package is installed. If using MkDocs, ensure it's installed in the same environment as MkDocs itself.","cause":"This error means the Python interpreter cannot find the `pymdown-extensions` package or its modules, usually due to the package not being installed, installed in a different environment, or an issue with Python's path.","error":"ModuleNotFoundError: No module named 'pymdownx'"},{"fix":"If `mkdocs-minify-plugin` is in use, either disable it or switch `Arithmatex` to its 'default' mode with proper MathJax configuration as outlined in the documentation. Ensure your MathJax/KaTeX configuration explicitly looks for the `Arithmatex` generic output patterns (e.g., `\\(...\\)` and `\\[...\\]`) and that `processEnvironments` is enabled for `\\begin{}`...`\\end{}` blocks.","cause":"When using the `Arithmatex` extension in generic mode with MkDocs, math rendering may fail if there are conflicts with other plugins, notably `mkdocs-minify-plugin`, or if MathJax/KaTeX is not correctly configured to process the generic output format.","error":"Arithmatex Generic Mode Not Working in MkDocs"},{"fix":"Ensure the Markdown syntax for tabs and nested code blocks is correct. If migrating from `pymdownx.tabbed` to `pymdownx.blocks.tab`, disable `pymdownx.tabbed` in `mkdocs.yml` as they are not meant to be used together. Verify that `pymdownx.superfences` (which handles code block highlighting) is also correctly configured if using `pymdownx.tabbed` or `pymdownx.blocks.tab`.","cause":"This issue often arises when the syntax for code blocks within `pymdownx.tabbed` (or its newer block-style equivalent `pymdownx.blocks.tab`) is incorrect, or if `pymdownx.tabbed` and `pymdownx.blocks.tab` are used simultaneously, causing conflicts due to identical output.","error":"Code blocks with new pymdownx.tabbed not rendering"},{"fix":"Identify the conflicting packages. You might need to either upgrade/downgrade the conflicting packages to a compatible version, or install `pymdown-extensions` with a specific version that satisfies all dependencies. For example, `pip install pymdown-extensions==<compatible_version>` or use `pip install --no-deps <package_name>` and manage dependencies manually (with caution).","cause":"This message indicates a dependency conflict where different installed packages require incompatible versions of `pymdown-extensions` (or other shared libraries), preventing a clean installation or upgrade.","error":"ERROR: pip's dependency resolver does not currently take into account all the packages that are installed."}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"10.21.2","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"10.21.2","pypi_latest":"10.21.2","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"pymdown-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.15,"mem_mb":5.7,"disk_size":"25.1M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"pymdown-extensions","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":5.7,"disk_size":"25.1M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"pymdown-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.9,"import_time_s":0.12,"mem_mb":5.7,"disk_size":"26M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"pymdown-extensions","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.14,"mem_mb":5.7,"disk_size":"26M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"pymdown-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.17,"mem_mb":5.9,"disk_size":"26.1M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"pymdown-extensions","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.21,"mem_mb":5.9,"disk_size":"26.1M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"pymdown-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2,"import_time_s":0.15,"mem_mb":5.9,"disk_size":"27M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"pymdown-extensions","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.16,"mem_mb":5.9,"disk_size":"27M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"pymdown-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.14,"mem_mb":5.8,"disk_size":"17.8M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"pymdown-extensions","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":5.8,"disk_size":"17.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"pymdown-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.8,"import_time_s":0.15,"mem_mb":5.8,"disk_size":"19M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"pymdown-extensions","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.16,"mem_mb":5.8,"disk_size":"19M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"pymdown-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.18,"mem_mb":6.1,"disk_size":"17.6M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"pymdown-extensions","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.17,"mem_mb":6.1,"disk_size":"17.5M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"pymdown-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.8,"import_time_s":0.14,"mem_mb":5.9,"disk_size":"19M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"pymdown-extensions","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.15,"mem_mb":5.9,"disk_size":"19M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"pymdown-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.09,"mem_mb":5.6,"disk_size":"23.2M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"pymdown-extensions","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.12,"mem_mb":5.6,"disk_size":"23.2M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"pymdown-extensions","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":2.4,"import_time_s":0.09,"mem_mb":5.6,"disk_size":"24M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"pymdown-extensions","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.13,"mem_mb":5.6,"disk_size":"24M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}