Each new [release](https://github.com/plausible/analytics/releases) of Plausible contains specific instructions on how to upgrade from the previous version. This guide outlines the general upgrade steps and explains how to manage versions.

### Version Management

Plausible Community Edition (CE) follows a versioning system inspired by [Intended Effort Versioning](https://jacobtomlinson.dev/effver/). Available versions can be found on [GitHub Packages](https://github.com/plausible/analytics/pkgs/container/community-edition).

The default `latest` tag refers to the most recent stable version, but it's recommended to pin your version for more control:

- **Major version pinning:**  
  Use <kbd>ghcr.io/plausible/community-edition:v2</kbd> to allow minor and patch upgrades while staying on version 2.
  
- **Minor version pinning:**  
  Use <kbd>ghcr.io/plausible/community-edition:v2.1</kbd> to allow only patch upgrades within version 2.1.

- **Patch version pinning:**  
  Use <kbd>ghcr.io/plausible/community-edition:v2.1.4</kbd> to pin to a specific version. Recommended.

Security patches and bug fixes are not backported, so upgrading is essential to ensure you receive the latest updates. New versions are announced on the [releases page](https://github.com/plausible/analytics/releases) and documented in the [Changelog](https://github.com/plausible/analytics/blob/master/CHANGELOG.md). To stay updated, you can subscribe to releases by clicking <kbd>Watch → Custom → Releases</kbd> on the [plausible/analytics](https://github.com/plausible/analytics) page.

### General Upgrade Steps

For minor version upgrades (e.g., v2.1.x to v2.1.y):

```bash
$ cd plausible-ce # or wherever you cloned this repo
$ git pull origin v2.1.4 # fetch the new version
$ docker compose up -d # update the running containers
```

Clean up old images:

```bash
$ docker images --filter=reference='*plausible*'
$ docker rmi <image_id> # remove old unused images
```

### Major Version Upgrades

Upgrading to a major version (e.g., v1.x to v2.x) may require additional steps like data migrations. Always review the specific upgrade instructions provided in the release notes (e.g., [v2.0.0](https://github.com/plausible/analytics/releases/tag/v2.0.0)).