Error: Unrecognised theme 'material' about mkdocs-material

[robmerki]

SOLVED!

@JerryC8080 thank you so much for your help.

I had at some point installed mkdocs via Homebrew and later switched to the pip install. Somewhere my config paths had become mixed up.

Solution:

$ brew uninstall --force mkdocs

$ pip uninstall mkdocs

$ pip install mkdocs

[JerryC8080]

@ksingh7 @g0dlight

Your are suggested to make mkdocs and meterial on the save way.
Such as both installed by pip.

I meet the same problem when I installed mkdocs by brew install mkdocs and meterial by pip install mkdocs-meterial.

We can see the differ of variable theme_dir that mkdocs on different way installed.

On My Device:
On brew install mkdocs

$ mkdocs -v build
......
DEBUG   -  Config value: 'theme_dir' = ['/usr/local/Cellar/mkdocs/0.16.1_1/libexec/lib/python2.7/site-packages/mkdocs/themes/mkdocs', u'/usr/local/Cellar/mkdocs/0.16.1_1/libexec/lib/python2.7/site-packages/mkdocs/assets/search']
...

On pip install mkdocs

$ mkdocs -v build
...
DEBUG   -  Config value: 'theme_dir' = ['/usr/local/lib/python2.7/site-packages/mkdocs/themes/mkdocs', u'/usr/local/lib/python2.7/site-packages/mkdocs/assets/search']
...

And pip install mkdocs-meterial

$ pip install mkdocs-material

Requirement already satisfied: mkdocs-material in /usr/local/lib/python2.7/site-packages

So, Make mkdocs and themes install in the save directory.
Because mkdocs build and mkdocs serve command will load the same level directory to find theme.

Hope the way i solve my problem will be same on you.

[barisalhan]

SOLVED!

In the mkdocs.yml file, you should change this line as follows:

theme:
  name: 'material'

to this version,

theme:
  name: 'mkdocs'

OR

theme:
  name: 'readthedocs'

[squidfunk]

Added a new section called Troubleshooting:
http://squidfunk.github.io/mkdocs-material/getting-started/#troubleshooting

[squidfunk]

It has to be custom_dir, see:
https://squidfunk.github.io/mkdocs-material/getting-started/#configuration

[ksingh7]

Hi @squidfunk looking for pointers on this.

[urosjarc]

I think that you install material for python3.

[squidfunk]

Please provide some more details on

• Python version
• MkDocs version
• Material version

so I can reproduce this error.

[urosjarc]

@ksingh7 if you installed py3 pip is pointing on python3. Try this...

pip2 install ...

[ksingh7]

@squidfunk @urosjarc

Here are more details, will really appreciate your help to get this working

karasing-OSX:~$ pip list | grep -i material
mkdocs-material (0.2.4)
karasing-OSX:~$
karasing-OSX:~$ python --version
Python 2.7.11
karasing-OSX:~$ mkdocs --version
mkdocs, version 0.15.3
karasing-OSX:~$

[squidfunk]

Versions look good to me. I have actually no explanation because I cannot reproduce this error. Can you post on the mkdocs issue tracker? The material theme isn't found, so since you're the only one with this problem of which I know it may be a problem with mkdocs.

[squidfunk]

Closing issue due to inactivity.

[g0dlight]

I'm getting the same error

INFO    -  Building documentation... 
ERROR   -  Config value: 'theme'. Error: Unrecognised theme 'material'. The available installed themes are: readthedocs, mkdocs 

Aborted with 1 Configuration Errors!

[mattwelke]

It's probably worth documenting this issue in the documentation. I ran into it too, because I installed mkdocs using apt-get but then had to use pip anyways to install the material theme. The mix caused the issue for me. I had to uninstall mkdocs in apt-get and install it again using pip.

[squidfunk]

Agreed, I will add a note on this. Nevertheless it's more related to MkDocs than to Material, but it doesn't hurt to point it out.

[mattwelke]

Awesome. :)

Great looking theme by the way. My documentation for a project just looked 100x better using this. xD

[josetomas]

Hi!
I've been having the same problem. I uninstalled mkdocs from apt-get and installed directly from pip.
But when I want to use mkdocs serve I receive the following error:
bash: /usr/bin/mkdocs: No existe el archivo o el directorio (the file or directory doesn't exist).

[lopezunwired]

SOLVED!

@JerryC8080 thank you so much for your help.

I had at some point installed mkdocs via Homebrew and later switched to the pip install. Somewhere my config paths had become mixed up.

Solution:

$ brew uninstall --force mkdocs

$ pip uninstall mkdocs

$ pip install mkdocs

This worked for me too! In fact, I don't recall installing mkdocs with homebrew, but when you use 'force' it seemed to clean it up. I also noticed now I have two paths for python to look in.

[RoseauHan]

SOLVED!

@JerryC8080 thank you so much for your help.

I had at some point installed mkdocs via Homebrew and later switched to the pip install. Somewhere my config paths had become mixed up.

Solution:

$ brew uninstall --force mkdocs

$ pip uninstall mkdocs

$ pip install mkdocs

Work for me too! Thanks!

[xvilo]

It's weird that this is still happening, just updated 'mkdocs' with brew and this happened. These paths should be fixed

[squidfunk]

Don't install mkdocs via Homebrew. See the troubleshooting guide

[seekM]

I'm having this problem when using material via cloning from github.

I'm using Windows 10 and installed python (and pip) from its website.
I installed mkdocs with pip install mkdocs.

My setup:

PS C:\Users\User\Documents\music\project> python --version
Python 3.8.2
PS C:\Users\User\Documents\music\project> pip --version
pip 20.1 from c:\users\user\appdata\local\programs\python\python38-32\lib\site-packages\pip (python 3.8)
PS C:\Users\User\Documents\music\project> mkdocs --version
mkdocs, version 1.1 from c:\users\user\appdata\local\programs\python\python38-32\lib\site-packages\mkdocs (Python 3.8)

Then I'm doing git clone https://github.com/squidfunk/mkdocs-material.git from the same directory as described here

PS C:\Users\User\Documents\music\project> ls .\mkdocs-material\material\

    Verzeichnis: C:\Users\User\Documents\music\project\mkdocs-material\material

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
d-----       10.05.2020     21:51                .icons
d-----       10.05.2020     21:51                assets
d-----       10.05.2020     21:51                overrides
d-----       10.05.2020     21:51                partials
-a----       10.05.2020     21:51            150 404.html
-a----       10.05.2020     21:51           8912 base.html
-a----       10.05.2020     21:51             88 main.html
-a----       10.05.2020     21:51           2492 mkdocs_theme.yml
-a----       10.05.2020     21:51              0 __init__.py

and set it in my mkdocs.yml:

site_name: Test
nav:
    - Home: index.md
    
theme:
  name: mkdocs-material/material

PS C:\Users\User\Documents\music\project> mkdocs serve
INFO    -  Building documentation...
ERROR   -  Config value: 'theme'. Error: Unrecognised theme name: 'mkdocs-material/material'. The available installed themes are: mkdocs, readthedocs

Aborted with 1 Configuration Errors!

Other themes, e.g. readthedocs, work fine. material also works finde when I insatall it via pip, but I don't want that because its latest release doesn't seem to include the favicon bug fix yet. Any idea?

[seekM]

Oops, thanks!

[Atlas-Night-Out]

brew uninstall --force mkdocs

What paths are we suppose to use, its so frustrating and complaicated to know where the phython is installed and if you need to point to taht path or not?

I have so many different version on one pc and added them all in the path, and MK docs works ok but struggling to move over to windows 11 and finding MK docs is not working but I dont think I have added a path yet!

So i have just done a download and installed python 3.12.3 now and its gone into C:\Program Files\Python312
so do i point to that folder?

error I'm getting is ERROR - Config value 'theme': Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs

and

mkdocs serve
'mkdocs' is not recognized as an internal or external command,
operable program or batch file.

[squidfunk]

You just need to make sure that mkdocs and mkdocs-material are installed in same site packages folder, i.e., they use the exact same Python version. Unfortunately, I cannot assist with Windows-specific problems, as I'm not a Windows user 😅

[alexvoss]

The safest bet is to use a virtual environment, which should help you keep things in one place.

python -m venv myvenv
. myvenv\Scripts\activate

Replace the myvenv bit with something descriptive, to avoid confusion. Then use Pip to install MkDocs and Material.

I also set the PIP_REQUIRE_VIRTUALENV environment variable to avoid accidentally installing things into my global Python installs. I am not a regular Windows user either but these things are similar on all operating systems. Things can get confusing with multiple installs of Python whatever OS you use. Hope this helps.