How to pin InfluxDB Docker image tags

Pinning an InfluxDB Docker image tag keeps a container or Docker Compose service on the intended database generation during later pulls and redeployments. It matters most for stacks that still reference influxdb:latest, because that moving tag can shift from InfluxDB v2 to InfluxDB 3 Core when the official image metadata changes.

Docker Compose resolves image names after it reads the active compose.yaml file and any .env values. Printing the resolved image before pulling or recreating the service catches a fallback to latest while the running container is still unchanged.

Use influxdb:2 when an existing deployment must remain on InfluxDB OSS v2, influxdb:3-core or an exact 3.x-core tag for InfluxDB 3 Core, and an exact patch tag such as influxdb:2.9.1 when release control requires repeatable pulls. Tag pinning prevents an accidental major-generation change, but data-bearing upgrades still need backups and migration testing.

1. Change into the active Compose project directory.

   $ cd /srv/influxdb

2. Set the InfluxDB image variable to the intended tag.

   INFLUXDB_IMAGE=influxdb:2

   Keep influxdb:2 for an InfluxDB OSS v2 deployment. Use influxdb:3-core, influxdb:3.10-core, or another supported Core tag only after the deployment has been tested for InfluxDB 3 Core.

3. Confirm that Compose resolves the service to the pinned image.

   $ docker compose config --images
   influxdb:2

   No influxdb:latest entry should remain for the InfluxDB service. If compose.yaml hard-codes the image instead of using .env, replace the hard-coded tag there and run the same check again.

4. Pull the pinned image before replacing the running container.

   $ docker compose pull influxdb
    Image influxdb:2 Pulling
    Image influxdb:2 Pulled

5. Recreate only the InfluxDB service on the resolved image.

   $ docker compose up --detach --no-deps influxdb
    Container influxdb-influxdb-1 Recreate
    Container influxdb-influxdb-1 Recreated
    Container influxdb-influxdb-1 Starting
    Container influxdb-influxdb-1 Started

   Container recreation does not migrate data between InfluxDB major generations or roll back volume contents. Keep backups and migration tests separate from the tag pin.
   Related: How to back up and restore InfluxDB 3 Core

6. Check the image tag used by the recreated container.

   $ docker compose images influxdb
   CONTAINER             REPOSITORY   TAG   PLATFORM      IMAGE ID       SIZE    CREATED
   influxdb-influxdb-1   influxdb     2     linux/amd64   4ba9fe5b6043   292MB   9 days ago

7. Verify the running InfluxDB generation from inside the container.

   $ docker compose exec influxdb influxd version
   InfluxDB v2.9.1 (git: d4fa1941fd) build_date: 2026-05-11T20:48:40Z

   For an InfluxDB 3 Core service, use docker compose exec influxdb env -u LOG_FILTER influxdb3 --version and expect an InfluxDB 3 Core version line.