Built a Docker image that you need to share with a colleague? Here’s how you can distribute an image without the recipient needing to run
docker build themselves.
Sharing a pre-built image instead of a
Dockerfile lets you be sure your colleague is running the exact same software. Re-running the build could result in a subtly different environment. You’ve got two options to distribute your image, depending on the situation.
Use A Docker Registry
The easiest way to share a Docker image is to push it up to a Docker registry. This functionality is fully integrated into the Docker CLI. You don’t need to make any manual file transfers when using this method.
The default registry is Docker Hub. This allows you to publicly share images and gives you one private repository too. Create an account on Docker Hub, then run
docker login in your terminal. Supply your account details to connect the Docker CLI to your account.
Next build your image as normal, using
docker build. Add a tag that starts with your Docker Hub username:
docker build -t my-account/my-image:latest .
Then use the
docker push command to push the tagged image up to Docker Hub:
docker push my-account/my-image:latest
Now your image is safely stored in Docker Hub. Other users will be able to pull it down using the
docker pull or
docker run commands. You’re done sharing your image!
For real-world use, Docker Hub might not be sufficient. If you’re part of a development team, you’ll probably want to keep images on your own server, instead of the public Hub registry. You can create a self-hosted registry server instead to get private storage that’s fully compatible with the
docker push and
docker pull commands. This lets you easily share images with anyone who can access your private registry.
If using a registry isn’t an option, you can manually export Docker image archives instead. This functionality is also built into the Docker CLI. Build your image and then use the
docker save command to get a
tar archive of its contents:
docker save my-image:latest > my-image.tar
The export might take a few moments to complete. Docker will include everything needed to recreate the image – that’s all the layers in your
Dockerfile, as well as the layers inherited from your base image. The archive will also contain information on tags associated with the image.
As the output is a simple
tar file, you’re now free to distribute it in whichever way you choose. Archives could be quite large so you’ll usually be best off by uploading it to a file server or a cloud storage provider.
To use an exported image, run the
docker load command. This accepts a
tar archive produced by
docker save as an input stream. Docker will load the archive’s contents and add it to your list of local images.
docker load < my-image.tar
You’ll now see the newly imported image in your
docker images output. You’re ready to start a new container with
Exporting and importing images adds a few extra steps over using a Docker registry. You’ll need to manually transfer the file between the clients. Consequently, this approach is less suitable for frequent use, although it does have its benefits too.
Converting images to a
tar archive can be useful for long-term storage. If you’re running out of space on your registry server, archiving old images and uploading their
tars to backup file storage could be a cost-effective way to reclaim some capacity. You’d still be able to recover the image if you ever needed to in the future.
What About “docker export”?
Docker has another export-related command,
docker export. This should not be confused with
docker save. Whereas
save works with images,
export actually manages individual containers.
docker export will produce a
tar archive of a container’s filesystem. This can be used to restore a replica of the container on another machine. If you inspect the archive’s contents, you’ll see it’s just a regular Linux root filesystem, with directories like
docker export my-container > my-container.tar
docker export is useful if you want to snapshot a container for later restoration. However, container archives don’t import in the way you might first expect. As a container represents a live, running environment, you can’t “import” one directly. Instead, importing a container archive constructs a new image.
docker import my-container.tar my-image:latest
In this example, Docker will take the filesystem in
my-container.tar and automatically construct a new image called
my-image:latest. This will have the same filesystem but not the same base image or Docker configuration as the original container you exported.
Docker makes it easy to share application images and development environments with your collaborators. It’s usually best to push images to a centralized repository that everyone else can pull from. In some scenarios, it may make more sense to export an image to an archive that you distribute manually.
Docker also lets you export a container’s filesystem for later restoration to an image. Be careful when using this as it’s not an exact reconstruction and not all filesystem data gets included. Any volumes mounted to the original container won’t be included in the filesystem archive, so you should take steps to back up these separately.