Pin Your n8n Docker Image Version Tag

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.

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

    # image: n8nio/n8n:latest

    # CORRECT: Pin to a specific version

    image: n8nio/n8n:1.94.1
```text
```bash title="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."
```text
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](../security-best-practices/01-set-a-unique-encryption-key-and-back-it-up.md) | [Configure Payload Size and Binary Data Mode for Large Files](../performance-and-large-files/01-configure-payload-size-and-binary-data-mode-for-large-files.md)