`mkdocs serve` doesn't reload upon change anymore

[Skaronator]

Problem

Updated by @squidfunk with explanation + workarounds

When serving the documentation with mkdocs serve and making a change to a document in the docs folder, MkDocs does not automatically rebuild the documentation and reload the browser anymore. This was working before.

What is impacted

• Every new virtual environment created with a fresh Material for MkDocs installation
• Material for MkDocs' Docker image 9.6.21 and later (see below why)

Why this is happening

Click 8.3.0, which MkDocs depends on and has covered by its version range, includes some changes to how command line arguments are handled. It's still unclear whether MkDocs needs to adapt or the error is within Click. We're still waiting on the upstream maintainers to fix the issue.

Before Click 8.3.0, Click 8.2.2 was released and later yanked because of fatal behavior, so we limited the version range of Click to < 8.2.2 in 9.6.17 via https://github.com/squidfunk/mkdocs-material/issues/8375. However, this led to the problem that our users were unable to install Material for MkDocs alongside other packages that needed later versions of Click as reported in #8458, which is why we removed the version pin again in 9.6.21 (since 8.2.2 has been yanked by that time). The Docker images as of 9.6.21 contain the latest versions of Click that MkDocs requires, which is why they are affected as well.

Note that MkDocs is currently unmaintained, so it's unclear when a fix will land. However, we haven't been idle in the meantime: in https://github.com/squidfunk/mkdocs-material/discussions/8461, we explain how we are handling this situation and how we intend to move forward.

Temporary solution

There are two things you can do to work around this problem and restore live reload functionality:

Use the --livereload flag explicitly

mkdocs serve --livereload

Downgrade to Click 8.2.1

pip install click==8.2.1

Subscribe to this issue to be notified when something changes.

---

Original report

Context

No response

Bug description

After upgrading the mkdocs-material Docker image from ghcr.io/squidfunk/mkdocs-material:9.6.20 to ghcr.io/squidfunk/mkdocs-material:9.6.21, the live-reloading feature has stopped working.

When running mkdocs serve --dev-addr=0.0.0.0:7070, the server starts and serves the site correctly. However, it no longer detects changes to source files (like Markdown files or mkdocs.yml). Consequently, the site does not rebuild, and the browser page does not auto-refresh.

To confirm this was not a container-specific issue, I performed A/B testing with a local Python virtual environment. The same bug occurs when using mkdocs-material==9.6.21 installed via pip, while version 9.6.20 works as expected.

My environment is Windows 11 with WSL2 (Debian 13), with all files and commands being executed within the Linux environment.

Related links

N/A

Reproduction

This is basically just 1:1 the original guide. No special changes required.

9.6.21-mkdocs-serve-no-longer-watches-for-filechanges.zip

Steps to reproduce

1. Run mkdocs serve --dev-addr=0.0.0.0:7070
2. Modify index.md
3. Watch Log

with mkdocs-material==9.6.21

mkdocs serve --dev-addr=0.0.0.0:7070                           
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.22 seconds
INFO    -  [11:38:35] Serving on http://0.0.0.0:7070/

Nothing happens when modifing my index.md

with mkdocs-material==9.6.20

mkdocs serve --dev-addr=0.0.0.0:7070                           
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.21 seconds
INFO    -  [11:37:24] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [11:37:24] Serving on http://0.0.0.0:7070/
INFO    -  [11:37:28] Detected file changes
INFO    -  Building documentation...
INFO    -  [11:37:28] Reloading browsers
INFO    -  [11:37:30] Detected file changes
INFO    -  Building documentation...
INFO    -  [11:37:30] Reloading browsers

Browser

No response

Before submitting

• [x] I have read and followed the bug reporting guidelines.
• [x] I have attached links to the documentation, and possibly related issues and discussions.
• [x] I assure that I have removed all customizations before submitting this bug report.
• [x] I have attached a .zip file with a minimal reproduction using the built-in info plugin.

[squidfunk]

Thanks for reporting and already digging into the problem!

To confirm this was not a container-specific issue, I performed A/B testing with a local Python virtual environment. The same bug occurs when using mkdocs-material==9.6.21 installed via pip, while version 9.6.20 works as expected.

Does it also happen when you change the theme to mkdocs? More specifically, can you reproduce the problem on your machine when you create a new project with mkdocs new . and make changes to the index.md?

You can verify this by creating a new project and serving it:

mkdocs new test
cd test
mkdocs serve

[squidfunk]

Okay, so I've verified that this is not a problem exclusive to Material for MkDocs, but an issue that must be raised with the maintainers of MkDocs, since it can be reproduced with a minimal MkDocs site without even touching Material for MkDocs.

Here's a reproduction: mkdocs-livereload-bug.zip

Running the preview server with any of the following commands does not trigger a reload upon file change:

mkdocs serve
mkdocs serve --watch-theme
mkdocs serve --dirtyreload

Could I maybe ask you to take this upstream to the maintainers of MkDocs? Thanks!

[jonasnordlund]

I also ran into this now and the aforementioned version 9.6.21 somehow broke mkdocs even with the base theme on a project created from scratch, but downgrading the Material theme to 9.6.20 helped. I'm surprised a theme could do this even when not in use via mkdocs.yml but this seems to be happening here.

[squidfunk]

I also ran into this now and the aforementioned version 9.6.21 somehow broke mkdocs even with the base theme on a project created from scratch, but downgrading the Material theme to 9.6.20 helped. I'm surprised a theme could do this even when not in use via mkdocs.yml but this seems to be happening here.

As written in https://github.com/squidfunk/mkdocs-material/issues/8478#issuecomment-3360334559, it is not exclusive to Material for MkDocs. Any new MkDocs project you create will exhibit this behavior. Make sure to create a new virtual environment and install MkDocs from scratch. The Docker container of 9.6.20 works because it has a specific set of dependencies.

[facelessuser]

The only difference when downgrading mkdocs-material from 9.6.21 to 9.6.20 is click:

Installing collected packages: click, mkdocs-material
  Attempting uninstall: click
    Found existing installation: click 8.3.0
    Uninstalling click-8.3.0:
      Successfully uninstalled click-8.3.0
  Attempting uninstall: mkdocs-material
    Found existing installation: mkdocs-material 9.6.21
    Uninstalling mkdocs-material-9.6.21:
      Successfully uninstalled mkdocs-material-9.6.21
Successfully installed click-8.2.1 mkdocs-material-9.6.20

When I downgrade, live reload works. The problem would seem to be the click version (or maybe usage of click the new click version needs to be updated). I don't know what recent changes have occured in click.

[facelessuser]

Yeah, when I upgrade back to material 9.6.21, click doesn't update to 8.30 and then everything works with the latest Material and with MkDocs.

Changelog in click doesn't sound like it introduces a crazy new breaking feature between 8.2.1 and the latest, but it seems to be the cause. I don't think MkDocs is broken per say, nor do I think Material is broken per se, but click seems to be doing something different.

[squidfunk]

Aha! We pinned click in 9.6.17 to mitigate #8375, and removed it again in 9.6.21 to fix #8458. This means that this issue occurs in any Material for MkDocs version except for 9.6.17, 9.6.18, 9.6.19 and 9.6.20 due to the version pin. We, as downstream consumers of MkDocs, shouldn't pin click, as we'll be limiting the version ranges to users of Material for MkDocs as reported in #8458.

In any case, this must be addressed either in click, or in MkDocs, since MkDocs uses click for its CLI. Material for MkDocs does not make use of click. If anybody could take this upstream, that would be great. I'm a little tight on time right now to write a full bug report. I've posted a reproduction in https://github.com/squidfunk/mkdocs-material/issues/8478#issuecomment-3360334559.

[pawamoy]

Wait so Click 8.3.0 is bugged too regarding boolean flags 🤔 ? Could be related: https://github.com/pallets/click/issues/3084

[facelessuser]

Wait so Click 8.3.0 is bugged too regarding boolean flags 🤔 ? Could be related: pallets/click#3084

It appears so, but I haven't dug any deeper than what I posted above; downgrading click fixes the issue.

[Knight-of-Code]

https://github.com/mkdocs/mkdocs/issues/4032#issuecomment-3361401189

rolling back to click==8.2.1 restored previous file watching behaviour for mkdocs serve

This worked for me with docker image 9.6.21.

[alexvoss]

For those of us who are not primarily Python devs, you can also downgrade just Click with: pip install --force-reinstall click==8.2.1. This might be the more practical approach in the longer-term or if you have a specific reason to use the very latest version of Material.

[rjlasko]

I noticed this too. squidfunk/mkdocs-material:9.5.50 still works in this way. I did not have any success with the few images i tried in 9.6.x

[Skaronator]

@rjlasko ghcr.io/squidfunk/mkdocs-material:9.6.20 works fine for me as mentioned above. Make sure that you didn't cache anything (or reuse volumes that contains python dependencies)

[jaceklaskowski]

I'm on mac mini m4 and had to switch from podman to colima to have it working...again. HTH

[squidfunk]

It's still unclear whether this needs to be addressed in MkDocs' or click, but let's hope one of these issues gets fixed soon:

• https://github.com/mkdocs/mkdocs/issues/4032
• https://github.com/pallets/click/issues/3084

In the meantime, please use @alexvoss's workaround as mentioned in his comment:

pip install --force-reinstall click==8.2.1

[serkansk1543-max]

Контекст

Никакого ответа

Описание ошибки

После обновления образа Docker mkdocs-material с ghcr.io/squidfunk/mkdocs-material:9.6.20 до ghcr.io/squidfunk/mkdocs-material:9.6.21 функция перезагрузки в реальном времени перестала работать.

При запуске mkdocs serve --dev-addr=0.0.0.0:7070 сервер запускается и корректно обслуживает сайт. Однако он больше не обнаруживает изменения в исходных файлах (например, в файлах Markdown или mkdocs.yml). Следовательно, сайт не пересобирается, а страница в браузере не обновляется автоматически.

Чтобы убедиться, что проблема не связана с контейнером, я провёл A/B-тестирование с использованием локальной виртуальной среды Python. Та же ошибка возникает при использовании mkdocs-material==9.6.21 установленного через pip, в то время как версия 9.6.20 работает должным образом.

Моя среда — Windows 11 с WSL2 (Debian 13), все файлы и команды выполняются в среде Linux.

Ссылки по теме

N/A

Размножение

По сути, это просто копия оригинального руководства. Никаких особых изменений не требуется.

9.6.21-mkdocs-serve-no-longer-watches-for-filechanges.zip

Шаги по воспроизведению

1. Беги mkdocs serve --dev-addr=0.0.0.0:7070
2. Изменять index.md
3. Журнал наблюдения

с mkdocs-material==9.6.21

mkdocs serve --dev-addr=0.0.0.0:7070 INFO — Сборка документации... INFO — Очистка каталога сайта INFO — Документация собрана за 0,22 секунды INFO — [11:38:35] Обслуживание по адресу http://0.0.0.0:7070/ При изменении моего файла index.md ничего не происходит

с mkdocs-material==9.6.20

mkdocs serve --dev-addr=0.0.0.0:7070 INFO — Сборка документации... INFO — Очистка каталога сайта INFO — Документация собрана за 0,21 секунды INFO — [11:37:24] Наблюдение за путями на предмет изменений: 'docs', 'mkdocs.yml' ИНФОРМАЦИЯ — [11:37:24] Обслуживание по адресу http://0.0.0.0:7070/ ИНФОРМАЦИЯ — [11:37:28] Обнаружены изменения в файлах ИНФОРМАЦИЯ — Создание документации... ИНФОРМАЦИЯ — [11:37:28] Перезагрузка браузеров ИНФОРМАЦИЯ — [11:37:30] Обнаружены изменения в файлах ИНФОРМАЦИЯ — Создание документации... ИНФОРМАЦИЯ — [11:37:30] Перезагрузка браузеров

Браузер

Никакого ответа

Перед отправкой

• [x] Я прочитал и выполнил руководство по сообщению об ошибках.[x] Я прикрепил ссылки на документацию и, возможно, на связанные с ней проблемы и обсуждения.[x] Я заверяю вас, что удалил все настройки перед отправкой этого отчёта об ошибке.[x] Я прикрепил .zip-файл с минимальной воспроизводимой настройкой с использованием встроенного информационного плагина.

[squidfunk]

Since nothing has happened so far, I've updated the OP with an explanation what happens, what is impacted and two possible workarounds (one of which I just found out about).

[rikedyp]

For me also live reloading / hot reload is not working in my Linux virtual machine and in Docker where mkdocs version is 1.6.1 and mkdocs-material is 9.6.22. The recommended workaround does seem to work but I wanted to comment to make it easier for others who are searching for information about this issue using "live reload" and "hot reload" keywords as it took me while to find this thread.

[MihaelIsaev]

I'm using mkdocs servein Docker and found that live preview works in version 9.6.20, but not in versions 9.6.21 or 9.6.22.

docker pull squidfunk/mkdocs-material:9.6.20
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:9.6.20

[marco-lancini]

Confirmed happening also on 9.7.0

[squidfunk]

Unfortunately, it's still not fixed upstream. However, reloading works perfectly and is much faster in Zensical.

[boldandbusted]

Unfortunately, it's still not fixed upstream. However, reloading works perfectly and is much faster in Zensical.

That's good news! How can I do this with Zeniscal in Docker like we do with Material for MkDocs? Is there a doc I missed? A new container image? Thanks.

[Skaronator]

@boldandbusted Soon ™️ https://github.com/zensical/zensical/issues/12#issuecomment-3496258957

[johnthagen]

At the request of the Mkdocs maintainer, I opened an MR to temporarily pin to a working Click version

• https://github.com/mkdocs/mkdocs/pull/4058

It's awaiting review.

[M5oul]

Fixed upstream in click: https://github.com/pallets/click/issues/3084 https://github.com/pallets/click/pull/3152 Now waiting for next click release to include it.