- Thingsboard versioning
- Lifecycle & Support (How long versions are supported)
- Choosing the Right Version
- Docker Hub Tagging Strategy
- Compatibility & Deprecations
This guide explains how ThingsBoard versions are numbered, how long each version is supported, what kind of upgrade requires downtime, and which Docker tags to use in different environments. It’s written for platform administrators, SREs, DevOps engineers, and technical users who deploy and maintain ThingsBoard.
Thingsboard versioning
ThingsBoard version numbers reflect the scope of changes introduced in each release. This follows semantic versioning principles, helping you gauge the potential impact of upgrading. Thingsboard version numbers have four parts: MAJOR.MINOR.MAINTENANCE.PATCH. For example, version 4.2.1.0 indicates major version 4, minor version 2, maintenece 1 and patch level 0.
The version number is incremented based on the level of change included in the release.
| Level | Changes | Upgrade scripts required |
| MAJOR | Breaking changes, removed/deprecated APIs, major migrations, new features | Yes |
| MINOR | New features with backward compatibility | Yes |
| MAINTENANCE | Bug fixes/security vulnerabilities/framework upgrades that may require upgrade scripts | Yes |
| PATCH | Hotfix releases that do not require upgrade scripts (critical bugs/security fixes; no env/DB changes). | No |
Examples
4.2.0.0 — Initial 4.2 LTS release
4.2.0.2 — Two hotfixes later, no upgrade scripts required to move within 4.2.0.x
4.2.1.0 — First maintenance release; expect upgrade scripts
4.2.1.3 — Hotfixes on top of 4.2.1.0; zero‑downtime within 4.2.1.x
Lifecycle & Support (How long versions are supported)
ThingsBoard maintains Long‑Term Support (LTS) lines for production users. Customers using LTS releases can be confident that their critical systems will be protected and operate reliably.
-
LTS declaration: We announce a new LTS line each year; each LTS line is supported for 18 months from initial LTS GA (e.g., from 4.2.0.0 release date)
Active support includes:
- Bug fixes, security patches
- New MAINTENANCE (…x.0) and PATCH (…x.y) releases as needed
-
Major releases: When breaking changes are introduced.
-
Minor releases: Typically every three months.
-
Maintenance releases: When bug fixes need an upgrade script.
-
Patch releases: When bug fixes don`t need an upgrade script.
Choosing the Right Version
If you run production:
-
Prefer the latest LTS line in Active Support.
-
To stay up to date with hotfixes, track the line’s PATCH updates only (same MAINTENANCE number, e.g., 4.2.1.0 → 4.2.1.3).
-
Schedule maintenance windows to adopt new MAINTENANCE releases when needed (e.g., 4.2.0.x → 4.2.1.0).
Docker Hub Tagging Strategy
| Tag | Example | Purpose | Update Policy |
| M.m.P.p | 4.2.1.0 | Production | Immutable |
| M.m.P | 4.2.1-latest | Automatic safe patches | Floating (within 4.2.1.x) |
| latest | latest | For development/testing (non-LTS) | Floating (latest master release) |
Recommendations
-
Production: Pin to the immutable full tag (e.g., 4.2.1.0). You update only when you change the tag.
-
Auto security hotfixes (no downtime): Use 4.2.1.1, 4.2.1.2, … , but never jump to 4.2.2.0.
-
Avoid latest in production. It may include breaking changes and is not covered by the LTS policy.
Compatibility & Deprecations
-
API/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 flagged as deprecated in a Minor release will remain for at least one subsequent Minor before removal (or be guarded by feature flags when possible). Deprecations and removals are always called out in Release Notes.