Release Policy

This page explains how ThingsBoard versions are numbered, how long each release line is supported, how to upgrade between versions, and which Docker tags to use. It is intended for administrators, SREs, and DevOps engineers who deploy and maintain ThingsBoard.

A ThingsBoard version has four parts: MAJOR.MINOR.MAINTENANCE.PATCH, for example 4.3.1.6. The first two parts identify the release line: 4.3.0, 4.3.0.1, and 4.3.1.6 all belong to the 4.3 line.

Level	Contents	Upgrade script
MAJOR	Breaking changes, removed APIs, major migrations, new features	Required
MINOR	New features, backward compatible	Required
MAINTENANCE	Bug fixes, security fixes, framework upgrades	Not required
PATCH	Critical bug and security fixes	Not required

Moving to a newer MAINTENANCE or PATCH release of your line (for example, 4.3.0.1 → 4.3.1.6) does not need the upgrade script. Install the new version and start it: ThingsBoard detects the version change and applies any database changes in the background after startup. In a cluster, only one node applies them.

This applies when upgrading from 4.2.1 or later. Upgrading from an earlier version, including 4.2.0, requires the upgrade script; follow the upgrade instructions for your version.

Moving to a new MAJOR or MINOR version (for example, 4.2.1.2 → 4.3.1.6) requires running the upgrade script while ThingsBoard is stopped, so plan a maintenance window. A new release line supports upgrades only from the previous line; the upgrade instructions list the supported source versions. To skip a line, upgrade through each line in turn.

ThingsBoard maintains Long-Term Support (LTS) lines for production use.

Release type	Description	Support duration	Typical frequency
LTS	Announced yearly; for stable, long-term production use	18 months from initial LTS GA date	Annually
Standard	Releases between LTS lines, including new features	6 months from initial GA date	Every three months (MINOR)

1. Keep up with MAINTENANCE and PATCH releases of your line. They contain bug and security fixes and need no upgrade script.

2. Test custom UI before adopting a MAINTENANCE release. These releases may upgrade frameworks (for example, Angular 18 → 20 in 4.2.2). The core platform stays backward compatible, but custom widgets or CSS that rely on internal component structure or CSS variable names may break.

3. Plan a maintenance window to move to a new release line.

Tag	Example	Purpose	Update policy
Full version	4.3.1.6	Production	Immutable
MAJOR.MINOR.MAINTENANCE-latest	4.3.1-latest	Automatic patches	Floating, within 4.3.1.x
latest	latest	Not for Community Edition	Floating, newest release

Recommendations:

• Production: Pin the immutable full version tag. The version changes only when you change the tag.
• Automatic hotfixes: Use the -latest tag of your MAINTENANCE version (for example, 4.3.1-latest) to receive new 4.3.1.x patches automatically. It never moves to the next MAINTENANCE release; change the tag to adopt one.
• Do not use latest. The images are shared with ThingsBoard 4.4 and later, so latest points to 4.4, not to a Community Edition release.

• API and behavior compatibility is maintained within a MAJOR version whenever feasible. MINOR releases may deprecate features but should not break existing integrations without a migration path.
• Deprecation policy: Features deprecated in a MINOR release remain for at least one subsequent MINOR release before removal, or are guarded by feature flags where possible. Deprecations and removals are always documented in the release notes.