Troubleshooting¶
Theme not recognized¶
Operating systems:
Error: Unrecognized theme
mkdocs serve
# => INFO - Building documentation...
# => ERROR - Config value: 'theme'. Error: Unrecognised theme 'material'.
# => ...
# => ConfigurationError: Aborted with 1 Configuration Errors!
If you run into this error, the most common reason is that you installed MkDocs through some package manager (e.g. brew or apt-get) and Material for MkDocs through pip, so both packages end up in different locations. MkDocs only checks its install location for themes.
Inadequate permissions¶
Operating systems:
Error: Permission denied
pip install mkdocs-material
# => Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: '...'
# => Consider using the --user option or check the permissions.
When you're running the pre-installed version of Python on macOS, pip tries to install packages in a folder for which your user might not have the adequate permissions. There are three possible solutions for this, the recommended one of which is to use virtual environments:
If you're installing Material for MkDocs with pip, the easiest way to make sure that you end up with the correct versions and without any incompatibility problems between packages it to use a virtual environment. First, ensure that you have a Python version of 3 or higher installed:
python --version
If you're good to go, create and activate a virtual environment with:
python -m venv venv
source ./venv/bin/activate
Note that the second venv is the name of the folder where to create the virtual environment – you may choose it as you like. Your terminal should now print (venv) before the prompt and the python executable should be located inside the folder you just created.
Next, install Material for MkDocs with pip, which will download and install all packages in the venv folder you just created, including MkDocs and its dependencies:
pip install mkdocs-material
Verify that MkDocs and Material for MkDocs were both installed correctly:
mkdocs --version
mkdocs serve --help
MkDocs should list material as an option under the --theme flag. When you're finished working with MkDocs, you can exit the virtual environment with:
deactivate
Provide the --user flag to the install command and pip will install the package in a user-site location. While this is not a global installation, it's still not isolated and may lead to problems when you use different versions of Material for MkDocs in other projects:
pip install --user mkdocs-material
Upgrade your Python installation by installing Python with Homebrew. This should eliminate a lot of problems you will run into with pip. Yet, it's still not an isolated installation which may also lead to the same problems as installing in user space:
brew upgrade python