---
title: Upgrade Telegraf Controller
description: Upgrade Telegraf Controller by replacing the executable and restarting the service. Telegraf Controller applies pending database migrations automatically at startup.
url: https://docs.influxdata.com/telegraf/controller/install/upgrade/
estimated_tokens: 1570
publisher: InfluxData
canonical: https://docs.influxdata.com/telegraf/controller/install/upgrade/
date: '2026-08-25T08:20:28-06:00'
lastmod: '2026-08-25T08:20:28-06:00'
---

Upgrade Telegraf Controller by replacing the `telegraf_controller`executable with a newer version and restarting the service. On startup,
Telegraf Controller applies any pending database migrations automatically;
there is no separate migration step.

Before you upgrade, review the[release notes](/telegraf/controller/reference/release-notes/) for each
version between your current version and the target version.

* [Back up your database](#back-up-your-database)
* [Upgrade Telegraf Controller](#upgrade-telegraf-controller)
* [Verify the upgrade](#verify-the-upgrade)
* [Upgrade a high-availability cluster](#upgrade-a-high-availability-cluster)

## Back up your database

Back up your database before upgrading so you can restore it if the upgrade
fails:

* **SQLite** (default): stop Telegraf Controller, then copy the database
  file and, if present, its `-wal` and `-shm` companion files. For the
  default file locations, see[Default SQLite data locations](/telegraf/controller/install/#default-sqlite-data-locations).
* **PostgreSQL**: use your database or provider backup tooling, for example`pg_dump`.

## Upgrade Telegraf Controller

1. **Download the new Telegraf Controller executable.**

   [Download Telegraf Controller]()

   #### Telegraf Controller executable name ####

   The downloaded Telegraf Controller executable includes
   platform-specific information in the file name. This documentation
   assumes you rename the file to `telegraf_controller`, matching the[install instructions](/telegraf/controller/install/#download-and-install-telegraf-controller).

2. **Replace the installed executable and restart Telegraf Controller.**

   #### Linux ####

   ### Linux ###

   #### Upgrade a systemd service installation ####

   ```
   sudo systemctl stop telegraf-controller
   sudo mv telegraf_controller /opt/telegraf-controller/telegraf_controller
   sudo chmod +x /opt/telegraf-controller/telegraf_controller
   sudo systemctl start telegraf-controller
   ```

   If your service file uses a different working directory or executable path,
   replace the executable at that location instead.

   #### Upgrade an in-place installation ####

   1. Stop the running `telegraf_controller` process.

   2. Replace the existing executable with the new version and give it
      executable permissions:

      ```
      chmod +x telegraf_controller
      ```

   3. Restart Telegraf Controller:

      ```
      ./telegraf_controller
      ```

   ### macOS ###

   #### Prepare the downloaded executable ####

   1. Give `telegraf_controller` executable permissions:

      ```
      chmod +x telegraf_controller
      ```

   2. Remove the macOS quarantine attribute (if downloaded via browser):

      ```
      xattr -d com.apple.quarantine telegraf_controller
      ```

   #### Upgrade a LaunchDaemon installation ####

   ```
   sudo launchctl unload /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist
   sudo mv telegraf_controller /usr/local/bin/
   sudo launchctl load /Library/LaunchDaemons/com.influxdata.telegraf-controller.plist
   ```

   #### Upgrade an in-place installation ####

   1. Stop the running `telegraf_controller` process.

   2. Replace the existing executable with the new, prepared executable.

   3. Restart Telegraf Controller:

      ```
      ./telegraf_controller
      ```

   ### Windows ###

   #### Upgrade a Windows service installation ####

   In **Command Prompt or PowerShell**:

   ```
   nssm stop TelegrafController
   Move-Item -Force telegraf_controller.exe "C:\Program Files\TelegrafController\telegraf_controller.exe"
   nssm start TelegrafController
   ```

   #### Upgrade an in-place installation ####

   1. Close the running Telegraf Controller application.

   2. Replace the existing `telegraf_controller.exe` with the new version.

   3. Restart Telegraf Controller:

      ```
      ./telegraf_controller.exe
      ```

## Verify the upgrade

1. Confirm the installed executable reports the new version:

   #### Linux/macOS ####

   ```
   telegraf_controller --version
   ```

   ```
   ./telegraf_controller.exe --version
   ```

   The running version is also displayed in the Telegraf Controller web
   interface, at the bottom of the navigation menu.

2. Confirm the service is running, the web interface loads, and agents
   continue to report.

If Telegraf Controller fails to start after an upgrade, check the service
logs for migration errors and see[Troubleshoot installation](/telegraf/controller/install/troubleshoot/).

## Upgrade a high-availability cluster

Upgrade a [high-availability](/telegraf/controller/high-availability/)cluster by upgrading one node at a time. The cluster keeps serving
throughout: when you stop a node, any leadership it holds transfers to a
standby within a few seconds, and the remaining nodes continue to accept
agent heartbeats and serve the web interface and API.

> [!Important]
> #### Some releases require a full-cluster upgrade
>
> If a release is not compatible with earlier versions running against the
> upgraded database, the release notes call it out. For those releases,
> stop all nodes, replace the executable on each, and then start the nodes
> one at a time instead of upgrading node by node.

1. On one node, stop Telegraf Controller, replace the executable, and
   restart it, following the [steps above](#upgrade-telegraf-controller).
2. Wait for the node to report healthy through your load balancer’s[health checks](/telegraf/controller/high-availability/load-balancing/),
   and confirm the new version with `telegraf_controller --version`.
3. Repeat for each remaining node.

During a rolling upgrade:

* The first upgraded node applies any pending database migrations at
  startup. Migrations run under a cluster-wide lock, so nodes never run
  migrations concurrently; a node that starts while another is migrating
  waits for it to finish.
* Until every node is upgraded, the cluster runs mixed versions. Complete
  the roll promptly rather than leaving nodes on different versions.

#### Related

* [Install Telegraf Controller](/telegraf/controller/install/)
* [High availability](/telegraf/controller/high-availability/)
* [Telegraf Controller release notes](/telegraf/controller/reference/release-notes/)