v3.1.0

This release

• Introduces the new dynamic and more configurable tracking snippet and script (legacy scripts and snippets will still continue to work). See this doc for more details
• Supports a new optional property on events: interactive. See this doc for more details.
• Revamps dark theme
• ...other fixes and improvements listed below

Upgrade

Update the image used for plausible

_compose.yml

plausible:
- image: ghcr.io/plausible/community-edition:v3.0.1
+ image: ghcr.io/plausible/community-edition:v3.1.0

and restart the containers

_console

$ docker compose up -d

This will boot up the new version of the app.

Changelog

Added

• Custom events can now be marked as non-interactive in events API and tracker script: events marked as non-interactive are not counted towards bounce rate
• Ability to leave team via Team Settings > Leave Team
• Stats APIv2 now supports include.trim_relative_date_range - this option allows trimming empty values after current time for day, month and year date_range values
• Properties are now included in full site exports done via Site Settings > Imports & Exports
• Google Search Console integration settings: properties can be dynamically sought
• Weekly/monthly e-mail reports now contain top goal conversions
• Newly created sites are offered a new dynamic tracking script and snippet that's specific to the site
• Old sites that go to "Review installation" flow are offered the new script and snippet, along with a migration guide from legacy snippets, legacy snippets continue to function as before
• The new tracker script allows configuring transformRequest function to change event payloads before they're sent
• The new tracker script allows configuring customProperties function hook to derive custom props for events on the fly
• The new tracker script supports tracking form submissions if enabled
• The new tracker script automatically updates to respect site domain if it's changed in "Change domain" flow
• The new tracker script automatically updates to respect the following configuration options available in "New site" flows and "Review installation" flows: whether to track outbound links, file downloads, form submissions
• The new tracker script allows overriding almost all options by changing the snippet on the website, with the function plausible.init({ ...your overrides... }) - this can be unique page-by-page
• A new @plausible-analytics/tracker ESM module is available on NPM - it has near-identical configuration API and identical tracking logic as the script and it receives bugfixes and updates concurrently with the new tracker script
• Ability to enforce enabling 2FA by all team members

Removed

Changed

• A session is now marked as a bounce if it has less than 2 pageviews and no interactive custom events
• All dropmenus on dashboard are navigable with Tab (used to be a mix between tab and arrow keys), and no two dropmenus can be open at once on the dashboard
• Special path-based events like "404" don't need event.props.path to be explicitly defined when tracking: it is set to be the same as event.pathname in event ingestion; if it is explicitly defined, it is not overridden for backwards compatibility
• Main graph no longer shows empty values after current time for day, month and year periods
• Include bounce_rate metric in Entry Pages breakdown
• Dark mode theme has been refined with darker color scheme and better visual hierarchy
• Configuring shared links is now in a modal

Fixed

• Make clicking Compare / Disable Comparison in period picker menu close the menu
• Do not log page views for hidden pages (prerendered pages and new tabs), until pages are viewed
• Password-authenticated shared links now carry over dashboard params properly
• Realtime and hourly graphs of visit duration, views per visit no longer overcount due to long-lasting sessions, instead showing each visit when they occurred
• Fixed realtime and hourly graphs of visits overcounting
• When reporting only visitors and visits per hour, count visits in each hour they were active in
• Fixed unhandled tracker-related exceptions on link clicks within svgs
• Remove Subscription and Invoices menu from CE
• Fix email sending error "Mua.SMTPError" 503 Bad sequence of commands
• Make button to include / exclude imported data visible on Safari

v3.1.0-rc.1

This release fixes v3.1.0-rc.0, see the notes of that release for the full picture.

Upgrade guide from last stable release

Update the image used for plausible

_compose.yml

plausible:
- image: ghcr.io/plausible/community-edition:v3.0.1
+ image: ghcr.io/plausible/community-edition:v3.1.0-rc.1

and restart the containers

_console

$ docker compose up -d

Changes (since v3.1.0-rc.0)

Fixed

• Fixed issue with backfilling tracker script config

Changed

• Configuring shared links is now in a modal

v3.1.0-rc.0

This release

• Introduces the new dynamic and more configurable tracking snippet and script (legacy scripts and snippets will still continue to work). See this doc for more details
• Supports a new optional property on events: interactive. See this doc for more details.
• Revamps dark theme
• ...other fixes and improvements listed below

Upgrade

Update the image used for plausible

_compose.yml

plausible:
- image: ghcr.io/plausible/community-edition:v3.0.1
+ image: ghcr.io/plausible/community-edition:v3.1.0-rc.0

and restart the containers

_console

$ docker compose up -d

This will boot up the new version of the app.

Changelog

Added

• Custom events can now be marked as non-interactive in events API and tracker script: events marked as non-interactive are not counted towards bounce rate
• Ability to leave team via Team Settings > Leave Team
• Stats APIv2 now supports include.trim_relative_date_range - this option allows trimming empty values after current time for day, month and year date_range values
• Properties are now included in full site exports done via Site Settings > Imports & Exports
• Google Search Console integration settings: properties can be dynamically sought
• Weekly/monthly e-mail reports now contain top goal conversions
• Newly created sites are offered a new dynamic tracking script and snippet that's specific to the site
• Old sites that go to "Review installation" flow are offered the new script and snippet, along with a migration guide from legacy snippets, legacy snippets continue to function as before
• The new tracker script allows configuring transformRequest function to change event payloads before they're sent
• The new tracker script allows configuring customProperties function hook to derive custom props for events on the fly
• The new tracker script supports tracking form submissions if enabled
• The new tracker script automatically updates to respect site domain if it's changed in "Change domain" flow
• The new tracker script automatically updates to respect the following configuration options available in "New site" flows and "Review installation" flows: whether to track outbound links, file downloads, form submissions
• The new tracker script allows overriding almost all options by changing the snippet on the website, with the function plausible.init({ ...your overrides... }) - this can be unique page-by-page
• A new @plausible-analytics/tracker ESM module is available on NPM - it has near-identical configuration API and identical tracking logic as the script and it receives bugfixes and updates concurrently with the new tracker script

Removed

Changed

• A session is now marked as a bounce if it has less than 2 pageviews and no interactive custom events
• All dropmenus on dashboard are navigable with Tab (used to be a mix between tab and arrow keys), and no two dropmenus can be open at once on the dashboard
• Special path-based events like "404" don't need event.props.path to be explicitly defined when tracking: it is set to be the same as event.pathname in event ingestion; if it is explicitly defined, it is not overridden for backwards compatibility
• Main graph no longer shows empty values after current time for day, month and year periods
• Include bounce_rate metric in Entry Pages breakdown
• Dark mode theme has been refined with darker color scheme and better visual hierarchy

Fixed

• Make clicking Compare / Disable Comparison in period picker menu close the menu
• Do not log page views for hidden pages (prerendered pages and new tabs), until pages are viewed
• Password-authenticated shared links now carry over dashboard params properly
• Realtime and hourly graphs of visit duration, views per visit no longer overcount due to long-lasting sessions, instead showing each visit when they occurred
• Fixed realtime and hourly graphs of visits overcounting
• When reporting only visitors and visits per hour, count visits in each hour they were active in
• Fixed unhandled tracker-related exceptions on link clicks within svgs
• Remove Subscription and Invoices menu from CE
• Fix email sending error "Mua.SMTPError" 503 Bad sequence of commands

v3.0.1

This release contains a patch for the migration procedure (fixes #5319).
Functionally it is equivalent of https://github.com/plausible/analytics/releases/v3.0.0

Upgrade

Update the image used for plausible

_compose.yml

diff --git a/compose.yml b/compose.yml
index f5a0a7e..3e03415 100644
--- a/compose.yml
+++ b/compose.yml
@@ -11,7 +11,7 @@ services:
       start_period: 1m
 
   plausible_events_db:
-    image: clickhouse/clickhouse-server:24.3.3.102-alpine
+    image: clickhouse/clickhouse-server:24.12-alpine
     restart: always
     volumes:
       - event-data:/var/lib/clickhouse
@@ -27,12 +27,14 @@ services:
       nofile:
         soft: 262144
         hard: 262144
+    environment:
+      - CLICKHOUSE_SKIP_USER_SETUP=1
     healthcheck:
       test: ["CMD-SHELL", "wget --no-verbose --tries=1 -O - http://127.0.0.1:8123/ping || exit 1"]
       start_period: 1m
 
   plausible:
-    image: ghcr.io/plausible/community-edition:v2.1.5
+    image: ghcr.io/plausible/community-edition:v3.0.1
     restart: always
     command: sh -c "/entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh run"
     depends_on:

and restart the containers

v3.0.0

Warning

Please use 3.0.1 patch that contains fix for #5319

The highlights of this release are:

• Create teams, manage users and permissions
• Scroll depth, engagement time and (reworked) time on page metrics
• Segments feature: group filters into persistent, named presets

Upgrade

Update the image used for plausible

_compose.yml

diff --git a/compose.yml b/compose.yml
index f5a0a7e..3e03415 100644
--- a/compose.yml
+++ b/compose.yml
@@ -11,7 +11,7 @@ services:
       start_period: 1m
 
   plausible_events_db:
-    image: clickhouse/clickhouse-server:24.3.3.102-alpine
+    image: clickhouse/clickhouse-server:24.12-alpine
     restart: always
     volumes:
       - event-data:/var/lib/clickhouse
@@ -27,12 +27,14 @@ services:
       nofile:
         soft: 262144
         hard: 262144
+    environment:
+      - CLICKHOUSE_SKIP_USER_SETUP=1
     healthcheck:
       test: ["CMD-SHELL", "wget --no-verbose --tries=1 -O - http://127.0.0.1:8123/ping || exit 1"]
       start_period: 1m
 
   plausible:
-    image: ghcr.io/plausible/community-edition:v2.1.5
+    image: ghcr.io/plausible/community-edition:v3.0.0
     restart: always
     command: sh -c "/entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh run"
     depends_on:

and restart the containers

_console

$ docker compose up -d

This will boot up the new version of the app.

Changelog

The following changes have been made since 2.1.5:

Added

• Ability to sort by and compare the exit_rate metric in the dashboard Exit Pages > Details report
• Add top 3 pages into the traffic spike email
• Two new shorthand time periods 28d and 91d available on both dashboard and in public API
• Average scroll depth metric
• Scroll Depth goals
• Dashboard shows comparisons for all reports
• UTM Medium report and API shows (gclid) and (msclkid) for paid searches when no explicit utm medium present.
• Support for case_sensitive: false modifiers in Stats API V2 filters for case-insensitive searches.
• Add text version to emails #4674
• Add acquisition channels report
• Add filter is not for goals in dashboard #4983
• Add Segments feature
• Support ["is", "segment", [<segment ID>]] filter in Stats API
• Time on page metric is now sortable in reports
• Plausible tracker script now reports maximum scroll depth reached and time engaged with the site in an engagement event. These are reported as sd and e integer parameters to /api/event endpoint respectively. If you're using a custom proxy for plausible script, please ensure that these parameters are being passed forward.
• Plausible tracker script now reports the version of the script in the v parameter sent with each request.
• Add support for creating and managing teams owning multiple sites
• Introduce "billing" team role for users
• Introduce "editor" role with permissions greater than "viewer" but lesser than "admin"
• Support behavioral filters has_done and has_not_done on the Stats API to allow filtering sessions by other events that have been completed.
• time_on_page metric is now graphable, sortable on the dashboard, and available in the Stats API and CSV and GA4 exports/imports

Removed

• Internal stats API routes no longer support legacy dashboard filter format.
• Dashboard no longer shows "Unique visitors" in top stats when filtering by a goal which used to count all users including ones who didn't complete the goal. "Unique conversions" shows the number of unique visitors who completed the goal.

Changed

• Default period for brand new sites is now today rather than last 28 days. On the next day, the default changes to last 28 days.
• Increase decimal precision of the "Exit rate" metric from 0 to 1 (e.g. 67 -> 66.7)
• Increase decimal precision of the "Conversion rate" metric from 1 to 2 (e.g. 16.7 -> 16.67)
• The "Last 30 days" period is now "Last 28 days" on the dashboard and also the new default. Keyboard shortcut T still works for last 30 days.
• Last 7d and 30d periods do not include today anymore
• Filters appear in the search bar as ?f=is,page,/docs,/blog&f=... instead of ?filters=((is,page,(/docs,/blog)),...) for Plausible links sent on various platforms to work reliably.
• Details modal search inputs are now case-insensitive.
• Improved report performance in cases where site has a lot of unique pathnames
• Plausible script now uses fetch with keepalive flag as default over XMLHttpRequest. This will ensure more reliable tracking. Reminder to use compat script variant if tracking Internet Explorer is required.
• The old /api/health healtcheck is soft-deprecated in favour of separate /api/system/health/live and /api/system/health/ready checks
• Changed top bar filter menu and how applied filters wrap
• Main graph now shows revenue with relevant currency symbol when hovering a data point
• Main graph now shows - instead of 0 for visit duration, scroll depth when hovering a data point with no visit data
• Make Stats and Sites API keys scoped to teams they are created in
• Remove permissions to manage sites guests and run destructive actions from team editor and guest editor roles in favour of team admin role
• Time-on-page metric has been reworked. It now uses engagement events sent by plausible tracker script. We still use the old calculation methods for periods before the self-hosted instance was upgraded. Warnings are shown in the dashboard and API when legacy calculation methods are used.
• Always set site and team member limits to unlimited for Community Edition
• Stats API now supports more date_range shorthand options like 30d, 3mo.
• Stop showing Plausible footer when viewing stats, except when viewing a public dashboard or unembedded shared link dashboard.

Fixed

• Fix fetching favicons from DuckDuckGo when the domain includes a pathname
• Fix visitors.csv (in dashboard CSV export) vs dashboard main graph reporting different results for visitors and visits with a time:minute interval.
• The tracker script now sends pageviews when a page gets loaded from bfcache
• Fix returning filter suggestions for multiple custom property values in the dashboard Filter modal
• Fix typo on login screen
• Fix Direct / None details modal not opening
• Fix year over year comparisons being offset by a day for leap years
• Breakdown modals now display correct comparison values instead of 0 after pagination
• Fix database mismatch between event and session user_ids after rotating salts
• /api/v2/query no longer returns a 500 when querying percentage metric without visitors
• Fix current visitors loading when viewing a dashboard with a shared link
• Fix Conversion Rate graph being unselectable when "Goal is ..." filter is within a segment
• Fix Channels filter input appearing when clicking Sources in filter menu or clicking an applied "Channel is..." filter
• Fix Conversion Rate metrics column disappearing from reports when "Goal is ..." filter is within a segment
• Graph tooltip now shows year when graph has data from multiple years

v3.0.0-rc.6

Another follow-up to pre-release 3.0.0-rc.0

On top of original rc.0 this contains all the Community Edition upgrade/startup fixes + latest changes, namely:

Added

• Ability to sort by and compare the exit_rate metric in the dashboard Exit Pages > Details report
• Two new shorthand time periods 28d and 91d available on both dashboard and in public API

Changed

• Default period for brand new sites is now today rather than last 28 days. On the next day, the default changes to last 28 days.
• Increase decimal precision of the "Exit rate" metric from 0 to 1 (e.g. 67 -> 66.7)
• Always set site and team member limits to unlimited for Community Edition
• Stats API now supports more date_range shorthand options like 30d, 3mo.

---

Full changelog: v2.1.5...v3.0.0-rc.6

---

Warning

ClickHouse upgrade is necessary. See below.

Use the following diff to test the pre-release:

diff --git a/compose.yml b/compose.yml
index f5a0a7e..3e03415 100644
--- a/compose.yml
+++ b/compose.yml
@@ -11,7 +11,7 @@ services:
       start_period: 1m
 
   plausible_events_db:
-    image: clickhouse/clickhouse-server:24.3.3.102-alpine
+    image: clickhouse/clickhouse-server:24.12-alpine
     restart: always
     volumes:
       - event-data:/var/lib/clickhouse
@@ -27,12 +27,14 @@ services:
       nofile:
         soft: 262144
         hard: 262144
+    environment:
+      - CLICKHOUSE_SKIP_USER_SETUP=1
     healthcheck:
       test: ["CMD-SHELL", "wget --no-verbose --tries=1 -O - http://127.0.0.1:8123/ping || exit 1"]
       start_period: 1m
 
   plausible:
-    image: ghcr.io/plausible/community-edition:v2.1.5
+    image: ghcr.io/plausible/community-edition:v3.0.0-rc.6
     restart: always
     command: sh -c "/entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh run"
     depends_on:

v3.0.0-rc.4

Another follow-up to pre-release 3.0.0-rc.0

This one should address issue with "disappearing sites" for people trying out previous release candidates.

Warning

ClickHouse upgrade is necessary. See below.

Use the following diff to test the pre-release:

diff --git a/compose.yml b/compose.yml
index f5a0a7e..3e03415 100644
--- a/compose.yml
+++ b/compose.yml
@@ -11,7 +11,7 @@ services:
       start_period: 1m
 
   plausible_events_db:
-    image: clickhouse/clickhouse-server:24.3.3.102-alpine
+    image: clickhouse/clickhouse-server:24.12-alpine
     restart: always
     volumes:
       - event-data:/var/lib/clickhouse
@@ -27,12 +27,14 @@ services:
       nofile:
         soft: 262144
         hard: 262144
+    environment:
+      - CLICKHOUSE_SKIP_USER_SETUP=1
     healthcheck:
       test: ["CMD-SHELL", "wget --no-verbose --tries=1 -O - http://127.0.0.1:8123/ping || exit 1"]
       start_period: 1m
 
   plausible:
-    image: ghcr.io/plausible/community-edition:v2.1.5
+    image: ghcr.io/plausible/community-edition:v3.0.0-rc.4
     restart: always
     command: sh -c "/entrypoint.sh db createdb && /entrypoint.sh db migrate && /entrypoint.sh run"
     depends_on:

v3.0.0-rc.3

This is a follow-up to pre-release 3.0.0-rc.0

Tries to address issues with Cloak Vault during migrations.

Upgrade

Update the image used for plausible

_compose.yml

plausible:
- image: ghcr.io/plausible/community-edition:v2.1.5
+ image: ghcr.io/plausible/community-edition:v3.0.0-rc.3

and restart the containers

_console

$ docker compose up -d

v3.0.0-rc.2

This is a follow-up to pre-release 3.0.0-rc.0

Contains faulty migrations patch.

Upgrade

Update the image used for plausible

_compose.yml

plausible:
- image: ghcr.io/plausible/community-edition:v2.1.5
+ image: ghcr.io/plausible/community-edition:v3.0.0-rc.2

and restart the containers

_console

$ docker compose up -d

v3.0.0-rc.0

Warning

In order to test the pre-release, please use https://github.com/plausible/analytics/releases/tag/v3.0.0-rc.4 patch.

The highlights of this release are:

• Create teams, manage users and permissions
• Scroll depth, engagement time and (reworked) time on page metrics
• Segments feature: group filters into persistent, named presets

Upgrade

Update the image used for plausible

_compose.yml

plausible:
- image: ghcr.io/plausible/community-edition:v2.1.5
+ image: ghcr.io/plausible/community-edition:v3.0.0-rc.0

and restart the containers

_console

$ docker compose up -d

This will boot up the new version of the app.

Changelog

The following changes have been made since 2.1.5:

Added

• Add top 3 pages into the traffic spike email
• Two new shorthand time periods 28d and 90d available on both dashboard and in public API
• Average scroll depth metric
• Scroll Depth goals
• Dashboard shows comparisons for all reports
• UTM Medium report and API shows (gclid) and (msclkid) for paid searches when no explicit utm medium present.
• Support for case_sensitive: false modifiers in Stats API V2 filters for case-insensitive searches.
• Add text version to emails #4674
• Add acquisition channels report
• Add filter is not for goals in dashboard #4983
• Add Segments feature
• Support ["is", "segment", [<segment ID>]] filter in Stats API
• Time on page metric is now sortable in reports
• Plausible tracker script now reports maximum scroll depth reached and time engaged with the site in an engagement event. These are reported as sd and e integer parameters to /api/event endpoint respectively. If you're using a custom proxy for plausible script, please ensure that these parameters are being passed forward.
• Plausible tracker script now reports the version of the script in the v parameter sent with each request.
• Add support for creating and managing teams owning multiple sites
• Introduce "billing" team role for users
• Introduce "editor" role with permissions greater than "viewer" but lesser than "admin"
• Support behavioral filters has_done and has_not_done on the Stats API to allow filtering sessions by other events that have been completed.
• time_on_page metric is now graphable, sortable on the dashboard, and available in the Stats API and CSV and GA4 exports/imports

Removed

• Internal stats API routes no longer support legacy dashboard filter format.
• Dashboard no longer shows "Unique visitors" in top stats when filtering by a goal which used to count all users including ones who didn't complete the goal. "Unique conversions" shows the number of unique visitors who completed the goal.

Changed

• Increase decimal precision of the "Conversion rate" metric from 1 to 2 (e.g. 16.7 -> 16.67)
• The "Last 30 days" period is now "Last 28 days" on the dashboard and also the new default. Keyboard shortcut T still works for last 30 days.
• Last 7d and 30d periods do not include today anymore
• Filters appear in the search bar as ?f=is,page,/docs,/blog&f=... instead of ?filters=((is,page,(/docs,/blog)),...) for Plausible links sent on various platforms to work reliably.
• Details modal search inputs are now case-insensitive.
• Improved report performance in cases where site has a lot of unique pathnames
• Plausible script now uses fetch with keepalive flag as default over XMLHttpRequest. This will ensure more reliable tracking. Reminder to use compat script variant if tracking Internet Explorer is required.
• The old /api/health healtcheck is soft-deprecated in favour of separate /api/system/health/live and /api/system/health/ready checks
• Changed top bar filter menu and how applied filters wrap
• Main graph now shows revenue with relevant currency symbol when hovering a data point
• Main graph now shows - instead of 0 for visit duration, scroll depth when hovering a data point with no visit data
• Make Stats and Sites API keys scoped to teams they are created in
• Remove permissions to manage sites guests and run destructive actions from team editor and guest editor roles in favour of team admin role
• Time-on-page metric has been reworked. It now uses engagement events sent by plausible tracker script. We still use the old calculation methods for periods before the self-hosted instance was upgraded. Warnings are shown in the dashboard and API when legacy calculation methods are used.

Fixed

• Fix fetching favicons from DuckDuckGo when the domain includes a pathname
• Fix visitors.csv (in dashboard CSV export) vs dashboard main graph reporting different results for visitors and visits with a time:minute interval.
• The tracker script now sends pageviews when a page gets loaded from bfcache
• Fix returning filter suggestions for multiple custom property values in the dashboard Filter modal
• Fix typo on login screen
• Fix Direct / None details modal not opening
• Fix year over year comparisons being offset by a day for leap years
• Breakdown modals now display correct comparison values instead of 0 after pagination
• Fix database mismatch between event and session user_ids after rotating salts
• /api/v2/query no longer returns a 500 when querying percentage metric without visitors
• Fix current visitors loading when viewing a dashboard with a shared link
• Fix Conversion Rate graph being unselectable when "Goal is ..." filter is within a segment
• Fix Channels filter input appearing when clicking Sources in filter menu or clicking an applied "Channel is..." filter
• Fix Conversion Rate metrics column disappearing from reports when "Goal is ..." filter is within a segment
• Graph tooltip now shows year when graph has data from multiple years