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.
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:
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 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 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.
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.