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:
Then use the docker push command to push the tagged image up to Docker Hub:
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.
Exporting Images
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:
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.
You’ll now see the newly imported image in your docker images output. You’re ready to start a new container with docker run.
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 /bin, /etc and /usr.
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.
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.
RELATED: How to Get Started with Github’s New Docker Container Registry
Summary
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.
