`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 #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 #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

• I have read and followed the bug reporting guidelines.
• I have attached links to the documentation, and possibly related issues and discussions.
• I assure that I have removed all customizations before submitting this bug report.
• 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 #8478 (comment), 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 #8478 (comment).

[pawamoy]

Wait so Click 8.3.0 is bugged too regarding boolean flags 🤔 ? Could be related: pallets/click#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.