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.

Related: How to run InfluxDB 3 Core with Docker
Related: How to use an env file with Docker Compose
Related: How to run a Docker Compose upgrade workflow

Steps to pin InfluxDB Docker image tags:

  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.