How to Update n8n Safely (Docker Compose)

To update n8n safely with Docker Compose, first back up your n8n data and database, then read the release notes and change the n8n image in docker-compose.yml to a specific new version tag. After that, run docker compose pull and docker compose up -d, and watch the logs while database migrations finish. Keep the previous image until you are sure the update works, so you can roll back by restoring the backup and switching to the old tag. This guide applies to any self-hosted n8n running in Docker Compose on Ubuntu 22.04 or 24.04, including Cloudesta n8n hosting, where n8n comes pre-installed in Docker on a Cloud VPS.

Prerequisites

• Root or sudo SSH access to the server running n8n.
• n8n running through Docker Compose (the docker compose plugin, v2).
• At least 3 GB of free disk space for the new image and your backups. Check this with df -h /.
• A quiet time window. Active executions are interrupted while the container restarts.

1. Why should you update n8n, and how do you read the release notes?

n8n releases often. Updates bring security fixes, new nodes and fixes for integrations whose third-party APIs have changed. If you skip many versions, you collect many changes at once, and that makes problems harder to trace. Before every update, read these two sources:

• The release notes at docs.n8n.io/release-notes/ or on the n8n GitHub releases page.
• The breaking changes file in the n8n repository at packages/cli/BREAKING-CHANGES.md. It lists changes that need action from you, such as renamed environment variables, removed nodes or new defaults.

Look for every version between your current version and the target version, not only the target itself. Major version jumps (for example 1.x to 2.x) almost always come with a migration guide. Read that guide in full before you start.

2. How do I back up n8n before updating?

Go to the directory that contains your Compose file. If you are not sure where it is, ask Docker:

docker ps --format '{{.Names}}\t{{.Image}}'
docker inspect n8n --format '{{ index .Config.Labels "com.docker.compose.project.working_dir" }}'

Replace n8n with your container name if it is different. Next, back up the Compose and environment files. Then stop n8n and archive its data volume. The volume holds the SQLite database (if you use SQLite) and the encryption key file.

cd /path/to/compose-dir
mkdir -p ~/n8n-backups
cp docker-compose.yml .env ~/n8n-backups/ 2>/dev/null
docker volume ls          # find the exact volume name, e.g. n8n_n8n_data
docker compose stop n8n
sudo docker run --rm -v n8n_n8n_data:/data -v ~/n8n-backups:/backup alpine \
  tar czf /backup/n8n_data-$(date +%F).tar.gz -C /data .

If n8n uses PostgreSQL, also dump the database while the Postgres container is still running. Adjust the service, user and database names to match your file.

docker compose exec -T postgres pg_dump -U n8n -d n8n > ~/n8n-backups/n8n-db-$(date +%F).sql

3. How do I check which n8n version I'm running?

Start the container again and ask n8n for its version:

docker compose start n8n
docker compose exec n8n n8n --version

Write this number down. It is your rollback target.

4. Should I pin a version tag or use latest?

Pin a version. With latest, any pull or rebuild can silently move you to a new major version, and you cannot tell which version you were running before. Edit docker-compose.yml so the image line names an exact version:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:1.110.1   # example: use the version you chose
    restart: unless-stopped

If you run queue mode with separate worker or webhook services, give every n8n service the same tag. Mixed versions between the main instance and the workers cause failures.

5. How do I pull and start the new n8n version?

docker compose pull
docker compose up -d

up -d recreates only the containers whose image or configuration changed. Your volumes and data are kept.

6. Do n8n database migrations run automatically?

Yes. On first start, the new version upgrades the database schema by itself. Follow the logs while this happens:

docker compose logs -f --tail=100 n8n

You may see Migrations in progress, please do NOT stop the process. Wait until the log says the editor is accessible. On large databases this can take several minutes. Do not restart the container during a migration, because an interrupted migration is the most common way an n8n database gets damaged. Press Ctrl+C to stop following the logs. This does not stop the container.

7. How do I remove old n8n images?

Each n8n image uses several hundred MB of disk. Keep the previous image for a few days in case you need to roll back. After that, remove it:

docker image ls docker.n8n.io/n8nio/n8n
docker image rm docker.n8n.io/n8nio/n8n:1.105.3   # the old tag
docker image prune -f                             # removes dangling layers
docker system df

8. How do I roll back n8n to the previous version?

Once migrations have run, an older n8n may not start against the newer schema. The reliable way back is to restore your backup and then run the old tag:

docker compose stop n8n
# set image back to the old tag in docker-compose.yml, then restore data:
sudo docker run --rm -v n8n_n8n_data:/data -v ~/n8n-backups:/backup alpine \
  sh -c "rm -rf /data/* /data/.[!.]* ; tar xzf /backup/n8n_data-YYYY-MM-DD.tar.gz -C /data"
docker compose up -d

For PostgreSQL, drop and recreate the database, then load the dump with psql before you start n8n. n8n also provides n8n db:revert, which undoes one migration at a time. You must run it with the newer version before you switch tags. Restoring the backup is simpler and safer.

9. How do I update Ubuntu and Docker itself?

Docker Engine and the Compose plugin are updated through apt, together with the operating system:

sudo apt update && sudo apt upgrade -y
docker version && docker compose version
[ -f /var/run/reboot-required ] && echo "Reboot needed"

When Docker is upgraded, the daemon restarts. Containers with restart: unless-stopped or always come back up on their own. Do OS updates and n8n updates separately, so that if something breaks you know which change caused it. Reboot when the kernel was updated. If the server does not come back after a reboot, open a support ticket. Rescue mode and console access are handled by Cloudesta.

Verify it works

• docker compose ps shows n8n as Up, not Restarting.
• docker compose exec n8n n8n --version prints the new version.
• You can log in to the editor at https://n8n.example.com and your workflows and credentials are listed.
• You can open one important workflow and run it manually, and a test webhook URL responds.
• Over the next hour, the Executions list shows scheduled workflows running.

Common problems

A node shows errors or "unrecognized node type" after the update

The node was renamed, removed or changed. Search the breaking changes file for the node name. Then open the workflow, replace or re-add the node, and map its fields again. For community nodes, update them from Settings → Community nodes so they are compatible with the new version.

Workflows stopped working after a major version

Major versions change defaults and environment variables, and can disable features. Check the migration guide for settings you need to add to .env. If production is affected, roll back as described in section 8. Then test the upgrade on a copy of your data on a second VPS first.

Pull fails with "no space left on device"

Old images and build cache have filled the disk. Run docker system df to see what is using space. Then remove unused images with docker image prune -a. Do not run this while you still need the old image for rollback. Also delete old backup archives you have already copied off the server. If you need more space permanently, request a plan upgrade by support ticket.

Container is stuck in a restart loop

Read the cause with docker compose logs --tail=200 n8n. The fix depends on the message:

• Mismatching encryption keys: restore the original N8N_ENCRYPTION_KEY.
• EACCES on /home/node/.n8n with a bind mount: fix ownership with sudo chown -R 1000:1000 ./n8n_data.
• A migration error: restore the backup and roll back, then report the error to n8n.

Frequently asked questions

How often should I update n8n?

Monthly is a good rhythm for most setups. Apply security releases promptly. Staying a few minor versions behind the newest release avoids most first-day bugs.

Will updating n8n delete my workflows or credentials?

No. They live in the database and the data volume, which docker compose up -d keeps. You should still take a backup first, because a failed migration can leave the data unusable.

Can I skip several versions in one update?

Yes. Migrations run in order, so you can jump several minor versions at once. Read the breaking changes for every version you skip, and for major versions follow the official migration guide.

Need help? If the update fails or you need provider-side help such as rescue mode or more disk space, open a ticket at https://cloudesta.com/submitticket.php. Include your n8n version, your target version and the last 50 lines of docker compose logs n8n.