Documentation

InfluxDB 3 Enterprise

Upgrade InfluxDB

Upgrade your InfluxDB 3 Enterprise version.

Before you upgrade

Before upgrading your InfluxDB 3 Enterprise cluster, review the release notes for compatibility requirements and then plan your upgrade strategy.

Verify your current version

Before upgrading, verify the InfluxDB 3 Enterprise version running on each node.

CLI Docker

influxdb3 --version
docker exec 
CONTAINER_NAME
 influxdb3 --version

Replace the following:

  • CONTAINER_NAME: The name of your InfluxDB 3 Enterprise container

The command returns version information similar to the following:

influxdb3 3.5.0

Verify your InfluxDB version

Before and after upgrading, verify the InfluxDB 3 Enterprise version running on your instance.

Upgrade an InfluxDB 3 instance

Install script systemctl Docker Docker Compose Windows

curl -O https://www.influxdata.com/d/install_influxdb3.sh \
&& sh install_influxdb3.sh enterprise
# 1. Download the new version
curl -L https://dl.influxdata.com/influxdb/releases/influxdb3-enterprise-3.5.0_linux_amd64.tar.gz \
  -o influxdb3-enterprise.tar.gz

# 2. Extract the archive
tar xvzf influxdb3-enterprise.tar.gz

# 3. Stop the service
sudo systemctl stop influxdb3

# 4. Install the new binary
sudo cp influxdb3 /usr/local/bin/

# 5. Start the service
sudo systemctl start influxdb3
docker stop 
CONTAINER_NAME

docker pull influxdb:enterprise
docker start 
CONTAINER_NAME

Replace the following:

  • CONTAINER_NAME: The name of your InfluxDB 3 Enterprise container
docker compose down
docker compose pull
docker compose up -d
# Download the latest Windows binary
Invoke-WebRequest `
  -Uri "https://dl.influxdata.com/influxdb/releases/influxdb3-enterprise-3.5.0-windows_amd64.zip" `
  -OutFile "influxdb3-enterprise.zip"

# Extract the binary
Expand-Archive -Path influxdb3-enterprise.zip -DestinationPath . -Force

# Stop the service, replace the binary, and start the service
Stop-Service influxdb3
Copy-Item -Path "influxdb3.exe" -Destination "C:\Program Files\InfluxData\influxdb3\" -Force
Start-Service influxdb3

Upgrade a multi-node cluster

Upgrade InfluxDB 3 Enterprise instances to newer versions using rolling upgrades to minimize downtime. When upgrading multi-node clusters, you need to understand catalog version constraints and the recommended upgrade order for different node modes.

Catalog version compatibility

InfluxDB 3 Enterprise uses a catalog to track metadata about tables, tags, and fields. Some versions introduce catalog version updates that affect how nodes can interoperate during rolling upgrades.

Important version transitions

  • 3.4.x: Introduced a catalog version update that requires all nodes to upgrade before catalog modifications can resume.
  • 3.2.x to 3.5.x: Nodes running 3.2.1 can temporarily coexist with nodes running 3.5.0, but catalog modifications are blocked until all nodes complete the upgrade.

During a rolling upgrade across a catalog version boundary, nodes running older versions cannot modify the catalog. This affects writes that add new tables, tags, or fields, but allows writes to existing tables, tags, and fields.

Multi-node upgrade procedure

Follow these steps to upgrade your InfluxDB 3 Enterprise deployment with minimal downtime.

The order in which you upgrade nodes affects the availability of catalog modifications during the upgrade. Different node modes have different impacts on catalog updates:

  • Ingest nodes: Primarily update the catalog when accepting writes that add new tables, tags, or fields via line protocol.
  • Query nodes: Can accept API requests that update the catalog (for example, influxdb3 create table), but less frequently than ingest nodes.
  • Compactor nodes: Rarely modify the catalog during normal operation.
  • Process nodes: Process data without modifying the catalog structure.

Recommended upgrade order:

  1. Ingest nodes: Upgrade ingest nodes first to restore catalog modification capability as quickly as possible. If you have multiple ingest nodes and can route traffic while one is down, upgrade them sequentially.
  2. Query nodes: Upgrade query nodes after upgrading all ingest nodes.
  3. Compactor nodes: Upgrade compactor nodes last, as they have minimal impact on catalog modifications.
  4. Process nodes: Can be upgraded at any time, as they don’t modify the catalog.

Perform a rolling upgrade

Follow these steps to upgrade each node in your deployment:

systemctl Docker Docker Compose

# 1. Stop the service
sudo systemctl stop influxdb3

# 2. Install the new version
# Follow the installation instructions for your platform:
# https://docs.influxdata.com/influxdb3/enterprise/install/

# 3. Start the service
sudo systemctl start influxdb3

# 4. Verify the version
influxdb3 --version

# 5. Check the node's health
influxdb3 query \
  --database _internal \
  --token ADMIN_TOKEN \
  "SELECT * FROM system.queries LIMIT 5"

Replace the following:

  • ADMIN_TOKEN: An admin token
# 1. Stop the container
docker stop 
CONTAINER_NAME


# 2. Pull the latest image
docker pull influxdb:enterprise

# 3. Start the container with the new image
# IMPORTANT: Adjust the docker run command to match your existing
# container configuration, including environment variables, volume mounts,
# object store settings, and network settings.
docker run -d \
  --name 
CONTAINER_NAME
 \
  -p 8181:8181 \
  -e INFLUXDB3_ENTERPRISE_LICENSE_EMAIL=your-email@example.com \
  -v ~/.influxdb3/data:/var/lib/influxdb3/data \
  influxdb:enterprise \
  influxdb3 serve \
  --node-id 
NODE_ID
 \
  --cluster-id 
CLUSTER_ID
 \
  --object-store 
OBJECT_STORE_TYPE
 \
  --data-dir /var/lib/influxdb3/data

# 4. Verify the version
docker exec 
CONTAINER_NAME
 influxdb3 --version

# 5. Check the node's health
docker exec 
CONTAINER_NAME
 influxdb3 query \
  --database _internal \
  --token 
ADMIN_TOKEN
 \
  "SELECT * FROM system.queries LIMIT 5"

Replace the following:

  • CONTAINER_NAME: The name of your InfluxDB 3 Enterprise container
  • NODE_ID: The node identifier for this instance
  • CLUSTER_ID: The cluster identifier for your deployment
  • OBJECT_STORE_TYPE: The object store type (for example, file, s3, azure, or google)
  • ADMIN_TOKEN: An admin token

Use the influxdb:enterprise image tag

The influxdb:enterprise tag always points to the latest InfluxDB 3 Enterprise release. Use docker pull influxdb:enterprise to pull the latest version, or specify a version tag directly (for example, influxdb:3.5.0-enterprise) to upgrade to a specific version.

If you use a cloud object store (S3, Azure, or Google Cloud), include the appropriate credentials and bucket configuration in the docker run command.

# 1. Stop the services
docker compose down

# 2. Update the image in your compose.yaml file
# Change the image version to: influxdb:enterprise

# 3. Start the services with the new image
docker compose up -d

# 4. Verify the version
docker compose exec influxdb3 influxdb3 --version

# 5. Check the node's health
docker compose exec influxdb3 influxdb3 query \
  --database _internal \
  --token 
ADMIN_TOKEN
 \
  "SELECT * FROM system.queries LIMIT 5"

Replace the following:

  • ADMIN_TOKEN: An admin token

Use the influxdb:enterprise image tag

The influxdb:enterprise tag always points to the latest InfluxDB 3 Enterprise release. Update the image: field in your compose.yaml to influxdb:enterprise to pull the latest version, or specify a version tag directly (for example, influxdb:3.5.0-enterprise) to upgrade to a specific version.

Repeat these steps for each remaining node in the recommended order.

Rolling upgrade constraints

Understand the constraints that apply during rolling upgrades to avoid unexpected write failures.

Writes during catalog version transitions

When upgrading from v3.3.x (or earlier) to v3.4.x, nodes running older versions cannot modify the catalog during the rolling upgrade.

Behavior by write type:

  • Writes to existing measurements, tags, and fields: Succeed on all nodes, regardless of version.
  • Writes that add new measurements, tags, or fields: Fail on nodes running older versions until those nodes are upgraded.

For example, if you’re upgrading from 3.2.1 to 3.5.0:

  • An ingest node running 3.2.1 can write data to existing measurements.
  • An ingest node running 3.2.1 cannot write data that adds new measurements, tags, or fields.
  • After upgrading the ingest node to 3.5.0, it can write data that adds new measurements, tags, or fields.

When a node running an older version receives a write that attempts to add a new measurement, the write fails with an error similar to:

Error: Catalog modification failed: node is running an older version

Troubleshooting cluster upgrades

Writes fail during upgrade

If writes fail during a rolling upgrade, verify that you’re not attempting to add new measurements, tags, or fields to nodes running older versions.

  1. Check the write payload to determine if it adds new measurements, tags, or fields
  2. Verify the node version that received the write
  3. Route writes to upgraded nodes or wait until all nodes complete the upgrade before adding new measurements, tags, or fields

Upgrade order issues

If you upgrade nodes out of the recommended order, you may experience longer periods where catalog modifications are blocked.

Version compatibility problems

If nodes fail to communicate after an upgrade, verify that all nodes are running compatible versions.

  1. Connect to each node and verify the version
  2. Review the release notes for your target version to identify any breaking changes or compatibility requirements.

Catalog version constraints

Different version transitions may have different catalog version constraints. The v3.3.x → v3.4.x transition has specific constraints, but other version transitions may differ.

Before upgrading, review the release notes for your target version to understand:

  • Whether the upgrade crosses a catalog version boundary
  • How long catalog modifications may be blocked during the upgrade
  • Any special upgrade procedures or constraints
upgrade administration catalog

Was this page helpful?

Thank you for your feedback!

© 2025 InfluxData, Inc.

What is your InfluxDB 3 Enterprise URL?

Customize your InfluxDB 3 Enterprise URL and we’ll update code examples for you.

Default
Custom

For more information, see InfluxDB Cloud regions or InfluxDB OSS URLs.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

New in InfluxDB 3.5

Key enhancements in InfluxDB 3.5 and the InfluxDB 3 Explorer 1.3.

See the Blog Post

InfluxDB 3.5 is now available for both Core and Enterprise, introducing custom plugin repository support, enhanced operational visibility with queryable CLI parameters and manual node management, stronger security controls, and general performance improvements.

InfluxDB 3 Explorer 1.3 brings powerful new capabilities including Dashboards (beta) for saving and organizing your favorite queries, and cache querying for instant access to Last Value and Distinct Value caches—making Explorer a more comprehensive workspace for time series monitoring and analysis.

For more information, check out:

InfluxDB Docker latest tag changing to InfluxDB 3 Core

On February 3, 2026, the latest tag for InfluxDB Docker images will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments.

If using Docker to install and run InfluxDB, the latest tag will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments. For example, if using Docker to run InfluxDB v2, replace the latest version tag with a specific version tag in your Docker pull command–for example:

docker pull influxdb:2