Migrating Docker Containers

What this article covers

• When you need to migrate containers.
• Exporting containers and images.
• Copying volumes.
• Moving Compose environments.
• Tips for smooth migrations.

Introduction: Migrating Docker Containers

Sometimes you need to move a Docker container to a different host. This might happen during hardware upgrades, cloud migrations, or infrastructure restructuring. A proper migration captures the image, configuration, and crucially, persistent data. Without volumes and environment variables, you’ll lose the most important parts during the move.

This article walks through migrating Docker containers, images, volumes, and Compose setups.

Key terms

• Export: Container filesystem as tar.
• Import: Convert tar into an image.
• Save/Load: Store an image as tar and reload it.
• Volume: Persistent container data.
• Commit: Convert a container into an image.
• Registry: Centralized image storage.
• rsync: File synchronization.
• Compose Override: Additional Compose file.

When to migrate

• New server.
• Switching cloud providers.
• Restoring from backup.
• Moving from development to production.
• Hardware replacement.

Saving a container as an image

docker commit mein-container mein-image:backup
docker save -o mein-image.tar mein-image:backup

On the new host:

docker load -i mein-image.tar

Exporting a container

docker export mein-container -o mein-container.tar
cat mein-container.tar | docker import - mein-image:importiert

Transferring images

docker save -o images.tar image1:latest image2:latest
docker load -i images.tar

Copying volumes

Read out and transfer volumes:

docker run --rm -v mein-volume:/data -v $(pwd):/backup alpine \
  tar -czf /backup/mein-volume.tar.gz -C /data .

On the new host:

docker run --rm -v mein-volume:/data -v $(pwd):/backup alpine \
  tar -xzf /backup/mein-volume.tar.gz -C /data

Using rsync

For large volumes:

rsync -avz /var/lib/docker/volumes/mein-volume/_data/ \
  benutzer@neuer-host:/var/lib/docker/volumes/mein-volume/_data/

Compose files

1. Copy all Compose files.
2. Copy .env files.
3. Back up volumes.
4. Start on the new host:

docker compose up -d

Using a registry

Push your images to a registry:

docker tag mein-image:latest registry.example.com:5000/mein-image:latest
docker push registry.example.com:5000/mein-image:latest

On the new host:

docker pull registry.example.com:5000/mein-image:latest

Checklist

• Images saved or pushed to registry.
• Volumes packed and copied.
• Compose files transferred.
• .env files transferred.
• Networks and ports verified.
• Secrets and certificates copied.
• Containers started on new host.
• Logs and functionality checked.

Tips

• Save containers as images rather than using export.
• Always back up volumes separately.
• Don’t modify the container after it’s running and before you commit it.
• Note version numbers.
• Test in a staging environment first.
• Create database dumps as an additional safeguard.
• Adjust DNS and external dependencies.

Common pitfalls

• Forgotten volume: Data missing after startup.
• Path mismatches: Bind mounts no longer work.
• Missing .env: Container fails to start.
• Architecture differences: An amd64 image won’t run on arm64.
• Network issues: New host IP or DNS problems.
• Missing secrets: Application can’t authenticate.

Further reading

• BotServ.de Docker Volume Backup
• BotServ.de Docker Backup Strategies
• BotServ.de Docker Registry
• BotServ.de Docker Compose

FAQ: Migrating Docker Containers

What’s the simplest approach? Save the image with docker save and volumes as tar, then load on the new host.

Do I need to stop the container? Yes, to ensure data consistency and a clean image.

Will volumes be lost with export? Yes, docker export only saves the container filesystem.

Can I copy volumes directly? Yes, using docker run with tar or rsync.

How do I transfer many images? Use a registry or save multiple images into a single tar file with docker save.

Sources and further reading

• Docker Export/Import: https://docs.docker.com/engine/reference/commandline/export/
• Docker Save/Load: https://docs.docker.com/engine/reference/commandline/save/
• Docker Volumes: https://docs.docker.com/storage/volumes/

Summary: Migrating Docker Containers

Container migration involves more than just moving an image. Volumes, environment variables, networks, and secrets all belong in the migration. Images can be transferred using docker save/load or a registry, and volumes can be copied via tar or rsync. A checklist and a quick functionality test help prevent data loss and downtime.