Pin Your n8n Docker Image Version Tag

Running n8nio/n8n:latest in production means any docker compose pull can introduce breaking changes, schema migrations, or incompatible node behavior without warning. Pin the image to a specific version instead, so every environment and teammate runs identical code and you upgrade deliberately after testing in staging. Rolling back is then a one-line change to the version tag.

Why pin the n8n Docker image version?

Using n8nio/n8n:latest in production means every docker compose pull could introduce breaking changes, schema migrations, or incompatible node behavior without warning. Pinning to a specific version gives you control over when and how you upgrade, and it ensures every team member and every deployment environment runs the exact same code.

Real-world example: You pin to 1.94.1 in your Compose file and only upgrade after testing the new version against your critical workflows in a staging environment.

How do you pin the version and upgrade safely?

services:
  n8n:
    # WRONG: Never use this in production

    # image: n8nio/n8n:latest

    # CORRECT: Pin to a specific version

    image: n8nio/n8n:1.94.1

upgrade-workflow.sh

#!/usr/bin/env bash
set -euo pipefail

NEW_VERSION="${1:?Usage: upgrade-workflow.sh <version>}"
COMPOSE_FILE="/opt/n8n/docker-compose.yml"

echo "=== n8n Upgrade: current -> ${NEW_VERSION} ==="

# Step 1: Update the image tag in docker-compose.yml

sed -i "s|n8nio/n8n:[0-9.]*|n8nio/n8n:${NEW_VERSION}|" "${COMPOSE_FILE}"

# Step 2: Pull the new image before stopping the current one

docker compose -f "${COMPOSE_FILE}" pull n8n

# Step 3: Run database backup before upgrade

/opt/scripts/backup-n8n-db.sh

# Step 4: Recreate only the n8n container

docker compose -f "${COMPOSE_FILE}" up -d n8n

# Step 5: Wait for health check to pass

echo "Waiting for n8n to become healthy..."
timeout 120 bash -c 'until docker inspect --format="{{.State.Health.Status}}" n8n-n8n-1 2>/dev/null | grep -q healthy; do sleep 5; done'

echo "Upgrade to ${NEW_VERSION} complete."

Pinned versions make your infrastructure reproducible. If an upgrade fails, rolling back is a one-line change to the version tag followed by docker compose up -d.

Related: Set a Unique Encryption Key and Back It Up · Configure Payload Size and Binary Data Mode for Large Files