Upgrade instructions

Upgrade ThingsBoard IoT Gateway to the latest version. Configuration files, connector settings, and custom extensions are preserved during the upgrade. For a first-time installation, see Installation options.

Download the .deb package.

wget https://github.com/thingsboard/thingsboard-gateway/releases/latest/download/python3-thingsboard-gateway.deb

Install the new package.
Terminal window
```
sudo apt install ./python3-thingsboard-gateway.deb -y
```
This automatically upgrades your existing Gateway installation without removing configuration or extension files (from Gateway version 3.7.6).

Restart the Gateway.

sudo systemctl restart thingsboard-gateway

Verify the upgrade. Confirm the service started successfully.
Terminal window
```
sudo systemctl status thingsboard-gateway
```

Configuration File Preservation

During the upgrade, all user configuration files are preserved, including connector configuration files, custom user extensions, and tb_gateway.json. An automatic backup of your configuration directory is also created:

Backup	Path
Connector configurations	`/etc/thingsboard-gateway/configs_backup.tar.gz`
User extensions	`/var/lib/thingsboard_gateway/extensions_backup.tar.gz`

Download the .rpm package.

wget https://github.com/thingsboard/thingsboard-gateway/releases/latest/download/python3-thingsboard-gateway.rpm

Install the new package.
Terminal window
```
sudo dnf install -y ./python3-thingsboard-gateway.rpm
```
This automatically upgrades your existing Gateway installation without removing configuration or extension files (from Gateway version 3.7.6).

Restart the Gateway.

sudo systemctl restart thingsboard-gateway

Verify the upgrade.

sudo systemctl status thingsboard-gateway

Configuration File Preservation

Backup	Path
Connector configurations	`/etc/thingsboard-gateway/configs_backup.tar.gz`
User extensions	`/var/lib/thingsboard_gateway/extensions_backup.tar.gz`

Stop and remove existing containers. This shuts down the Gateway gracefully without deleting volumes or configuration data.
Terminal window
```
docker compose down
```
Pull the latest Gateway image.
Terminal window
```
docker pull thingsboard/tb-gateway
```
Start the updated Gateway. The -d flag runs containers in detached mode.
Terminal window
```
docker compose up -d
```
Verify the upgrade. Watch the logs to confirm the Gateway is running correctly.
Terminal window
```
docker compose logs -f
```

Stop the Gateway.
If running as a systemd service:
Terminal window
```
sudo systemctl stop thingsboard-gateway
```
If running manually, stop it with Ctrl + C.
Upgrade the package.
Terminal window
```
pip install --upgrade thingsboard-gateway
```
Depending on your environment, use pip3 or python3 -m pip instead of pip. Add --user for a user-level installation.
Restart the Gateway.
If running as a systemd service:
Terminal window
```
sudo systemctl start thingsboard-gateway
```
If running manually:
Terminal window
```
thingsboard-gateway
```

Was this helpful?