Install Telegraf

Use this guide to install Telegraf on your system:

Review requirements
Download and install Telegraf
Deploy in Kubernetes with Helm
Verify the installation
Custom compile Telegraf
Nightly builds
Next steps

Requirements

Installation of the Telegraf package may require root or administrator privileges to complete successfully.

Supported operating systems

Telegraf supports Linux, macOS, Microsoft Windows, and FreeBSD. For each operating system, Telegraf supports releases that are under the vendor’s general support, not extended or paid support. Telegraf is written in Go and may also build and run on other operating systems supported by Go.

Networking

Telegraf offers multiple service input plugins that may require custom ports. Modify port mappings through the configuration file (telegraf.conf).

For Linux distributions, this file is located at /etc/telegraf for default installations.

For Windows distributions, the configuration file is located in the directory where you unzipped the Telegraf ZIP archive. The default location is C:\Program Files\InfluxData\telegraf.

NTP

Telegraf uses a host’s local time in UTC to assign timestamps to data. Use the Network Time Protocol (NTP) to synchronize time between hosts. If hosts’ clocks aren’t synchronized with NTP, the timestamps on the data might be inaccurate.

Download and install Telegraf

Recommended:: Before you open and install packages and downloaded files, use SHA checksum verification and GPG signature verification to ensure the files are intact and authentic.

SHA checksum and GPG signature verification are complementary checks.

For some Linux platforms, the installation instructions include steps to verify downloaded packages and binaries.

For more information, see the following:

Verify download integrity using SHA-256

For each released binary, InfluxData publishes the SHA checksum that you can use to verify that the downloaded file is intact and hasn’t been corrupted.

To use the SHA checksum to verify the downloaded file, do the following:

In the downloads page, select the Version and Platform for your download, and then copy the SHA256 checksum for the file.
Compute the SHA checksum of the downloaded file and compare it to the checksum you copied in the preceding step. For example, enter the following command in your terminal.

In the following examples, replace SHA256_CHECKSUM with the SHA256 checksum value that you copied from the downloads page.

Syntax

# Use 2 spaces to separate the checksum from the filename
echo "SHA256_CHECKSUM
  telegraf-1.39.3_linux_amd64.tar.gz" \
| sha256sum -c -

Example

The following sample code uses curl to download Telegraf, and then uses sha256sum to compare it to the checksum:

curl -s --location -O \
"https://dl.influxdata.com/telegraf/releases/telegraf-1.39.3_linux_amd64.tar.gz"
echo "SHA256_CHECKSUM
  telegraf-1.39.3_linux_amd64.tar.gz" \
| sha256sum -c -

If the checksums match, the output is the following. Otherwise, the command prints an error message.

telegraf-1.39.3_linux_amd64.tar.gz: OK

Verify file integrity and authenticity using GPG

Ubuntu & Debian RedHat & CentOS SLES & openSUSE FreeBSD Linux binaries macOS Windows Docker

Debian and Ubuntu users can install the latest stable version of Telegraf using the apt-get package manager.

Install from the InfluxData repository
Install from a .deb file

Install from the InfluxData repository

Run the following commands using apt-get to install Telegraf from the InfluxData repository:

Ubuntu 20.04 LTS and newer Older than Ubuntu 20.04

curl --silent --location -O https://repos.influxdata.com/influxdata-archive.key
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive.key 2>&1 \
| grep -q '^fpr:\+24C975CBA61A024EE1B631787C3D57159FC2F927:$' \
&& cat influxdata-archive.key \
| gpg --dearmor \
| sudo tee /etc/apt/keyrings/influxdata-archive.gpg > /dev/null \
&& echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive.gpg] https://repos.influxdata.com/debian stable main' \
| sudo tee /etc/apt/sources.list.d/influxdata.list
sudo apt-get update && sudo apt-get install telegraf

# influxdata-archive_compat.key GPG Fingerprint: 9D539D90D3328DC7D6C8D3B9D8FF8E1F7DF8B07E
curl --silent --location -O https://repos.influxdata.com/influxdata-archive_compat.key
gpg --show-keys --with-fingerprint --with-colons ./influxdata-archive_compat.key 2>&1 \
| grep -q '^fpr:\+9D539D90D3328DC7D6C8D3B9D8FF8E1F7DF8B07E:$' \
&& cat influxdata-archive_compat.key \
| gpg --dearmor \
| sudo tee /etc/apt/keyrings/influxdata-archive_compat.gpg > /dev/null
echo 'deb [signed-by=/etc/apt/keyrings/influxdata-archive_compat.gpg] https://repos.influxdata.com/debian stable main' \
| sudo tee /etc/apt/sources.list.d/influxdata.list
sudo apt-get update && sudo apt-get install telegraf

Install from a `.deb` file

To manually install the Debian package from a .deb file:

Download the latest Telegraf .deb release from the downloads page.
Run the following command (making sure to supply the correct version number for the downloaded file):
```
sudo dpkg -i telegraf_1.39.3-1_amd64.deb
```

To learn how to manually install the RPM package from a file, see the downloads page.

To use the yum package manager to install the latest stable version of Telegraf, follow these steps:

In your terminal, enter the following command to add the InfluxData repository to the yum configuration. The repository configuration references the InfluxData GPG key directly, so yum verifies package signatures against it.

cat <<EOF | sudo tee /etc/yum.repos.d/influxdata.repo
[influxdata]
name = InfluxData Repository - Stable
baseurl = https://repos.influxdata.com/stable/\$basearch/main
enabled = 1
gpgcheck = 1
gpgkey = https://repos.influxdata.com/influxdata-archive.key
EOF

Enter the following command to install telegraf from the repository.
```
sudo yum install telegraf
```

The telegraf configuration file is installed at /etc/telegraf/telegraf.conf.

The openSUSE Build Service provides RPM packages for SUSE Linux.

These packages are maintained in the community openSUSE Build Service Go repository, not by InfluxData.

To use the zypper package manager to install the latest stable version of Telegraf, follow these steps:

In your terminal, enter the following command to add the Go repository to the zypper configuration:
```
# add go repository
zypper ar -f obs://devel:languages:go/ go
```
Enter the following command to install telegraf.
```
# install latest telegraf
zypper in telegraf
```

Telegraf is part of the FreeBSD package system.

To use the pkg package manager to install the latest stable version of Telegraf, enter the following command:

sudo pkg install telegraf

The telegraf configuration file is installed at /usr/local/etc/telegraf.conf. Examples are installed at /usr/local/etc/telegraf.conf.sample.

Download the Telegraf binary archive for your architecture and verify its checksum. For 32-bit builds and other architectures, see the downloads page.

AMD64 (x86_64) ARM64 (AArch64)

curl -s --location -O \
https://dl.influxdata.com/telegraf/releases/telegraf-1.39.3_linux_amd64.tar.gz \
&& echo "SHA256_CHECKSUM
  telegraf-1.39.3_linux_amd64.tar.gz" \
| sha256sum -c -

curl -s --location -O \
https://dl.influxdata.com/telegraf/releases/telegraf-1.39.3_linux_arm64.tar.gz \
&& echo "SHA256_CHECKSUM
  telegraf-1.39.3_linux_arm64.tar.gz" \
| sha256sum -c -

Replace the following:

SHA256_CHECKSUM: the SHA256 checksum from the downloads page

Choose from the following options to install Telegraf for macOS:

To manually install Telegraf from a file, see the downloads page.
Install using Homebrew

Install using Homebrew

Users of macOS 10.8 and higher can install Telegraf using the Homebrew package manager.

The telegraf binary installed by Homebrew differs from the macOS .dmg builds available from the downloads page.

telegraf (Homebrew) isn’t a static binary.
telegraf (Homebrew) works with the Telegraf CPU plugin (due to Homebrew support for Cgo). The .dmg builds available on the downloads page don’t support the CPU plugin.

To install using Homebrew, do the following:

If you haven’t already, follow the instructions to install the Homebrew package manager.
Enter the following commands to update brew and install Telegraf:
```
brew update && brew install telegraf
```
The path where brew installs the telegraf.conf configuration file depends on your system architecture:
- ARM-based (Apple Silicon) systems: /opt/homebrew/etc/telegraf.conf
- Intel-based (x86_64) systems: /usr/local/etc/telegraf.conf

To start collecting metrics, see Get started with Telegraf. To run Telegraf as a background service, see Administer Telegraf.

Download and run Telegraf as a Windows service

Installing a Windows service requires administrative permissions. To run PowerShell as an administrator, see Launch PowerShell as administrator.

In PowerShell as an administrator, do the following:

Use the following commands to download the Telegraf Windows binary and extract its contents to C:\Program Files\InfluxData\telegraf\:

iwr `
https://dl.influxdata.com/telegraf/releases/telegraf-1.39.3_windows_amd64.zip `
-UseBasicParsing `
-OutFile telegraf-1.39.3_windows_amd64.zip
Expand-Archive .\telegraf-1.39.3_windows_amd64.zip `
-DestinationPath 'C:\Program Files\InfluxData\telegraf\'

Choose one of the following steps to place your telegraf.exe and telegraf.conf files in C:\Program Files\InfluxData\telegraf:
- Move the telegraf.exe and telegraf.conf files from C:\Program Files\InfluxData\telegraf\telegraf-1.39.3 to the parent directory C:\Program Files\InfluxData\telegraf. For example:
```
cd "C:\Program Files\InfluxData\telegraf";
mv .\telegraf-1.39.3\telegraf.* .
```
- Or, create a Windows symbolic link (Symlink) for C:\Program Files\InfluxData\telegraf that points to the extracted directory.
The remaining instructions assume that telegraf.exe and telegraf.conf files are stored in C:\Program Files\InfluxData\telegraf or that you created a Symlink to point to this directory.
Optional: Enable a plugin to collect Windows-specific metrics. For example, uncomment the inputs.win_services plugin configuration line:
```
...
# # Input plugin to report Windows services info.
# # This plugin ONLY supports Windows
[[inputs.win_services]]
...
```
Run the following command to install Telegraf and the configuration as a Windows service. For the --config option, pass the absolute path of the telegraf.conf configuration file.
```
.\telegraf.exe `
--config "C:\Program Files\InfluxData\telegraf\telegraf.conf" `
service install
```
To test that the installation works, enter the following command:
```
.\telegraf.exe `
--config C:\"Program Files"\InfluxData\telegraf\telegraf.conf --test
```
When run in test mode (using the --test flag), Telegraf runs once, collects metrics, outputs them to the console, and then exits. Test mode runs inputs, processors, and aggregators, but not outputs, so nothing is written to your destinations.
To start collecting data, run:
```
.\telegraf.exe service start
```

To manage the Telegraf Windows service and view its logs in the Windows Event Viewer, see Administer Telegraf and Troubleshoot Telegraf.

Use the official telegraf Docker image to run Telegraf in a container. Debian-based and Alpine-based images are available.

Pull the image:
```
docker pull telegraf
```

Generate a configuration file, or use an existing one, and mount it into the container:

docker run --rm \
--volume $PWD/telegraf.conf:/etc/telegraf/telegraf.conf:ro \
telegraf

If your configuration uses secret stores, the container might need a higher locked-memory limit. Use the --ulimit memlock=<bytes> option with docker run.

Deploy Telegraf in Kubernetes with Helm

For Kubernetes deployments, InfluxData provides several Helm charts:

telegraf: Deploy Telegraf as a single instance
telegraf-ds: Deploy Telegraf as a DaemonSet to run on every node
telegraf-operator: Deploy the Telegraf Operator for managing Telegraf instances declaratively

Verify the installation

To verify that Telegraf is installed and on your path, check the version:

telegraf version

On Windows:

.\telegraf.exe version

The output is the installed version, for example:

Telegraf v1.39.3 (git: HEAD@xxxxxx)

Custom-compile Telegraf

Use the Telegraf custom builder tool to compile Telegraf with only the plugins you need and reduce the Telegraf binary size.

Prerequisites
Build the custom builder tool
Run the custom builder to create a telegraf binary

Prerequisites

Follow the instructions to install Go for your system.
Create your Telegraf configuration file with the plugins you want to use.

Build the custom builder tool

Clone the Telegraf repository and then change into the repository directory. For example, enter the following command in your terminal:
```
git clone https://github.com/influxdata/telegraf.git && cd ./telegraf
```
To build the Telegraf custom builder tool, enter the following command:
```
make build_tools
```

Run the custom builder to create a `telegraf` binary

The custom builder builds a telegraf binary with only the plugins included in the specified configuration files or directories.

Run the custom_builder tool with at least one --config or --config-directory flag to specify Telegraf configuration files to build from.

--config: accepts local file paths and URLs.
--config-dir: accepts local directory paths.

You can include multiple --config and --config-dir flags.

Examples

Single Telegraf configuration

./tools/custom_builder/custom_builder --config /etc/telegraf.conf

Single Telegraf configuration and Telegraf configuration directory

./tools/custom_builder/custom_builder \
--config /etc/telegraf.conf \
--config-dir /etc/telegraf/telegraf.d

Remote Telegraf configuration

./tools/custom_builder/custom_builder \
--config http://url-to-remote-telegraf/telegraf.conf

After a successful build, you can view your customized telegraf binary within the top level of your Telegraf repository.

Update your custom binary

To add or remove plugins from your customized Telegraf build, edit your configuration file, and then run the custom builder to regenerate the Telegraf binary.

Nightly builds

Nightly builds are generated from the Telegraf master branch at midnight UTC. Use them to preview unreleased features and fixes. Nightly builds are not stable releases. Don’t use them in production.

Common artifacts:

Platform	Download
Debian/Ubuntu	amd64.deb, arm64.deb
RedHat/CentOS	x86_64.rpm, aarch64.rpm
Linux binary	linux_amd64.tar.gz, linux_arm64.tar.gz
macOS binary	darwin_amd64.tar.gz, darwin_arm64.tar.gz
Windows	windows_amd64.zip, windows_arm64.zip

For additional architectures, see the full nightly build list.

Nightly Docker images are available on quay.io:

# Debian-based image
docker pull quay.io/influxdb/telegraf-nightly:latest
# Alpine-based image
docker pull quay.io/influxdb/telegraf-nightly:alpine

Next steps

Get started with Telegraf: generate a configuration file and collect your first metrics.
Configure Telegraf: learn the configuration file structure, agent settings, and plugin options.
Administer Telegraf: run Telegraf as a service and troubleshoot problems.

Was this page helpful?

Thank you for your feedback!

Support and feedback

Thank you for being part of our community! We welcome and encourage your feedback and bug reports for Telegraf and this documentation. To find support, use the following resources:

Customers with an annual or support contract can contact InfluxData Support.

Edit this page Submit docs issue Submit Telegraf issue

Install Telegraf

Requirements

Supported operating systems

Networking

NTP

Download and install Telegraf

Syntax

Example

Install from the InfluxData repository

Install from a `.deb` file

Install using Homebrew

Download and run Telegraf as a Windows service

Deploy Telegraf in Kubernetes with Helm

Verify the installation

Custom-compile Telegraf

Prerequisites

Build the custom builder tool

Run the custom builder to create a `telegraf` binary

Examples

Single Telegraf configuration

Single Telegraf configuration and Telegraf configuration directory

Remote Telegraf configuration

Update your custom binary

Nightly builds

Next steps

Support and feedback

InfluxDB OSS 2.9.0: API tokens are hashed by default

Key enhancements in Explorer 1.9

InfluxDB 3.11 is now available

InfluxDB 3 Enterprise 3.11: A significant performance upgrade for complex time series workloads

Telegraf Enterprise is now generally available

InfluxDB Docker latest tag changing to InfluxDB 3 Core

Install Telegraf

Requirements

Supported operating systems

Networking

NTP

Download and install Telegraf

Syntax

Example

Install from the InfluxData repository

Install from a .deb file

Install using Homebrew

Download and run Telegraf as a Windows service

Deploy Telegraf in Kubernetes with Helm

Verify the installation

Custom-compile Telegraf

Prerequisites

Build the custom builder tool

Run the custom builder to create a telegraf binary

Examples

Single Telegraf configuration

Single Telegraf configuration and Telegraf configuration directory

Remote Telegraf configuration

Update your custom binary

Nightly builds

Next steps

Related

Support and feedback

Where are you running InfluxDB?

AWS

GCP

Azure

Default

Custom

Thank you for your feedback!

InfluxDB OSS 2.9.0: API tokens are hashed by default

Key enhancements in Explorer 1.9

InfluxDB 3.11 is now available

InfluxDB 3 Enterprise 3.11: A significant performance upgrade for complex time series workloads

Telegraf Enterprise is now generally available

InfluxDB Docker latest tag changing to InfluxDB 3 Core

Install from a `.deb` file

Run the custom builder to create a `telegraf` binary