I currently have Python3 as version 3.12.4 in my PATH. It was installed via Homebrew.

I have installed mkdocs using

pip3 install mkdocs

mkdocs --version says

mkdocs, version 1.6.0 from /Users/ronaldfischer/Library/Python/3.11/lib/python/site-packages/mkdocs (Python 3.11)

It mentions Python 3.11 because at time of installation, my Python3 in the PATH was still 3.11. Meanwhile, another homebrew installation updated Python to 3.12, so this is what I'm running now.

When I do a mkdocs serve, I get the error message

cannot find module 'pymdownx.superfences' (No module named 'pymdownx')

(superfences is referenced to in the mkdocs.yml file)

I figured that I need to install pymdown-extensions. My first approach

pip3 install pymdown-extensions

failed with error message

*This environment is externally managed. ... If you wish to install a Python application that isn't in Homebrew, it may be easiest to use 'pipx install xyz'.

So I installed pipx via Homebrew and then executed

pipx --include-deps pymdown-extensions

and added ~/.local/bin to my PATH. My .local/bin contains now a symlink

markdown_py -> /Users/ronaldfischer/.local/pipx/venvs/pymdown-extensions/bin/markdown_py

However, I still get the error message when running mkdocs.

When I do a

find ~ -name '*pymdownx*' 2>/dev/null

I don't get any matching files. This makes me wonder whether the package is correctly installed.

What did I do wrong, and - more importantly - how can I fix it?


I have not set the environment variable PYTHONPATH, since the docs about mkdocs don't mention it. I just wonder how my installed packages are supposed to be found without this variable.

  • You installed the mkdocs module in your python 3.11 install. Then you installed python 3.12. So if you execute python 3.12, the module is not installed. If you were to execute python 3.11, the module would be installed. Commented Jul 10 at 14:47
  • @MarcWilson : When Homebrew updated Python (without asking), it seemed to have removed the previous 3.11 version. I therefore uninstalled the package and re-installed it. I still get the same error message. Commented Jul 11 at 10:25

1 Answer 1


I noticed your question about installing MkDocs with pip. Since you're using Homebrew, a simpler solution is:

brew install mkdocs

Once installed, you can create a new documentation project with:

mkdocs new <project-name>

Switch to the project directory:

cd <project-name>

Finally, to serve the documentation locally, run:

mkdocs serve

This should help you get started with MkDocs more easily.

  • Good idea, but I still get the same error. Commented Jul 10 at 11:06

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .