mkdocs-material/docs/insiders/upgrade.md

How to upgrade

When upgrading Insiders, you should always check the version of Material for MkDocs which makes up the first part of the version qualifier, e.g., Insiders 4.x.x is currently based on 9.x.x:

9.x.x-insiders-4.x.x

If the major version increased, it's a good idea to consult the upgrade guide and go through the steps to ensure your configuration is up to date and all necessary changes have been made.

Depending on how you installed and what you want to upgrade to you need to run different commands:

=== "pip upgrade to release"

If you installed Insiders via `pip` and you want to upgrade to a
specific release, pick the tag from the [list of tags] and replace 
the tag at the end of the URL of the command given below:

```
pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git@9.4.2-insiders-4.42.0
```

=== "pip upgrade to latest development"

If you installed Insiders via `pip` and want to upgrade to the
latest development version, run:

```
pip install --upgrade --force-reinstall git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
```

The `--force-reinstall` option serves to make sure `pip` does, in fact,
install the latest development version, instead of deciding that  nothing
is to be done based on the version numbers.
```

=== "git upgrade"

If you installed Insiders via `git`, you will first need to check
out the version you want to install into your workspace. After
this is done, you can run `pip` to install that version.

First, make sure that your local clone is up-to-date with the
upstream repository by running `git pull`.

You can look up the tags using `git tag --sort -refname` or you
can consult the [list of tags]. Then, checkout the tag you want to
use by replacing the one given in the command below (twice)and running 
it from your workspace[^detached]:
  
  [^detached]:
    The `--detach` argument serves to tell `git` that you are ok to
    have your workspace in the [detached head] state, which is
    perfectly fine to have here.
    
  [detached head]: https://www.git-tower.com/learn/git/faq/detached-head-when-checkout-commit/

``` 
cd mkdocs-material 
git checkout --detach tags/9.4.2-insiders-4.42.0 
```

Now, change back to the parent directory in which your Git
repository lives and run `pip`:

```
cd .. 
pip install -e mkdocs-material
```