# Upgrading Docusaurus

Docusaurus versioning is based on the `major.minor.patch` scheme and respects [**Semantic Versioning**](https://semver.org/).

**Breaking changes** are only released on major version upgrades, and thoroughly documented in the following upgrade guides.

::::card-grid
:::card{title="To Docusaurus v3" href="/guides/migration-v3"}
:::
::::

## Troubleshooting upgrades

When upgrading Docusaurus you may experience issues caused by mismatching cached dependencies - there are a few troubleshooting steps you should perform to resolve these common issues before reporting a bug or seeking support.

### Run the `clear` command

This CLI command is used to clear a Docusaurus site's generated assets, caches and build artifacts.

```bash npm2yarn
npm run clear
```

### Remove `node_modules` and your lock file(s)

Remove the `node_modules` folder and your package manager's lock file using the following:

:::code-group
```bash title="Bash"
rm -rf node_modules yarn.lock package-lock.json
```

```powershell title="PowerShell"
@('node_modules','yarn.lock','package-lock.json') | Remove-Item -Force -Recurse -ErrorAction SilentlyContinue
```
:::

Then reinstall packages and regenerate the `lock` file using:

```bash npm2yarn
npm install
```

## Related pages

- [Docusaurus](../index.md)
- [Advanced Tutorials](./advanced.md)
- [Docs](../guides.md)
- [Api](./api.md)
- [Blog](./blog.md)
- [Browser support](./browser-support.md)
- [CLI](./cli.md)
- [Docusaurus Client API](./docusaurus-core.md)
- [Configuration](./configuration.md)
- [Deployment](./deployment.md)
- [Upgrading to Docusaurus v3](./migration-v3.md)
- [V2](./v2.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.