How to Transfer Docker Images Between Machines — Do You Need to Copy the Base Image Too?

Posted on by Rico

In daily DevOps or system administration work, we often build a new Docker image (e.g., XX) on one machine (say, Machine A) and want to move it to another (say, Machine B).
A common question arises:

If my image XX is built FROM another image YY, do I also need to copy YY to Machine B?

Short answer:
👉 No, you don’t need to copy YY separately.

🔍 Why Copying Only XX Is Enough

Docker images are composed of multiple layers.
When you build XX from YY, Docker simply adds new layers on top of the existing YY layers.

When you run docker save to export the image, Docker automatically includes all dependent parent layers (i.e., those from YY) in the exported archive.

So when you run docker load on the target machine, Docker reconstructs the complete image structure:

  • If any layers already exist locally, they’re skipped (de-duplicated).
  • Otherwise, all required layers are imported automatically.

💡 Recommended Ways to Transfer Images

Method 1: Using docker save / docker load (Offline Transfer)

# On Machine A
docker save -o xx.tar XX:tag

# Transfer the tar file to Machine B
docker load -i xx.tar

After loading, Machine B will have:

  • The XX image
  • All the base layers inherited from YY

Method 2: Using a Private or Public Registry (Online Transfer)

# On Machine A
docker tag XX:tag my-registry.example.com/ns/xx:tag
docker push my-registry.example.com/ns/xx:tag

# On Machine B
docker pull my-registry.example.com/ns/xx:tag

This approach automatically pulls only the missing layers, saving bandwidth and time — ideal for CI/CD or long-term deployments.

⚠️ Common Mistakes and Things to Watch Out For

  • ❌ Don’t use docker export / docker import
    These commands are for container file systems, not full image layers. They lose all image metadata and history.
  • ⚙️ Ensure platform architecture compatibility
    For example, images built for linux/amd64 won’t run on linux/arm64.
    If you need cross-platform support, use: docker buildx build --platform linux/amd64,linux/arm64 ...
  • 📦 To back up multiple images at once docker save YY:tag XX:tag -o both.tar

✅ Conclusion

Docker automatically handles image dependencies through shared layers.
So in practice:

You only need to copy or push the target image (XX); the base image (YY) layers will be included or downloaded automatically.

📘 Further Reading