Docker images are immutable, i.e., their structure and contents cannot be altered after the build process finishes. However, if you want to make adjustments to a dockerized app, run a container from the image, make the changes inside the container, and commit them to a new Docker image.
In this tutorial, you will learn how to use docker commit to create an image based on a container.
docker commit Command
docker commit command allows users to create a new Docker image based on the contents of a container. The new image comprises the base image and a layer containing modifications made inside the container.
The following sections provide details about
docker commit and compare it to
docker push, a related image distribution command.
docker commit Syntax
docker commit command uses the following syntax:
docker commit [options] [container-id-or-name] [image-name]:[tag]
[tag] part of the command is optional. If you create an image without a tag, Docker defaults to
The command accepts the options listed in the table below:
|Include the name of the image author.
|Apply a Dockerfile instruction to the new image. Supported instructions are
|Include a custom message with the image.
|Pause the container during the commit operation. If the option is not specified, the command assumes the value is
Note: The docker commit command is an alias of docker container commit. The two commands are interchangeable.
docker commit vs. docker push
While frequently used together,
docker commit and
docker push serve different functions. The docker commit command creates a Docker image, and
docker push uploads it to a registry to simplify distribution.
The table below compares the commands:
|Creates an image from a container and saves it locally.
|Uploads a local image to a remote registry.
docker commit [container] [image]:[tag]
docker push [registry]/[image]:[tag]
docker container commit
docker image push
|Helps create image templates and iterate application versions.
|Enables sharing of the new image by making it readily available to remote team members.
Note: The commit operation transfers the modifications made to the base image but does not include data created by the application, such as Docker volume contents.
How to Commit Changes to a New Docker Image
The steps you must take to create a Docker image based on another image involves:
- Running a container from the base image.
- Making the necessary changes in the container.
- Committing the changes to a new image.
Follow the steps below to create a new Docker image using
docker run with the
-it flag to launch a container in the interactive mode and enable a terminal typing interface. Specify the interface shell as the last command argument.
docker run -it [image] [shell]
For example, to run a container based on the latest Ubuntu image and use a Bash shell to navigate it, type:
docker run -it ubuntu /bin/bash
Docker launches the container and opens a shell prompt inside it.
apt install nmap -y
The command downloads the necessary packages and installs them inside the running container.
3. Once you finish with the modifications, exit the container:
The container stops, and the terminal returns to the operating system's shell.
4. List all Docker containers on the system:
sudo docker ps -a
5. Locate and copy the ID of the container you modified.
6. Commit the changes to a new image by typing:
sudo docker commit [container-id] [new-image-name]
For example, the command below creates an image named ubuntu-with-nmap:
sudo docker commit c624caff45a8 ubuntu-with-nmap
If the operation is successful, the output displays the sha256 hash value of the image ID.
7. Verify that the image has been created by listing the locally available images:
sudo docker images
The new image appears on the list.
When to Commit Changes to a New Docker Image
There are two main reasons to use
docker commit for creating new image versions:
- Generating image templates. For example, if you always use a specific set of tools on Ubuntu, you can run an Ubuntu container, install the tools, and commit the changes to create a template image for future use.
- Creating quick application iterations. For example, when testing an application, you can make fixes and tweaks inside a container and then commit them to an image for sharing with a team or performing further testing.
After reading this tutorial, you should know how to commit changes to a Docker image. The article covered the syntax and options of the
docker commit command, described creating a new image from a container, and mentioned frequent use cases.
If you are interested in Docker, read our tutorial on how to set up and use Private Docker Registry.