docker commit Explained {With Examples}

February 14, 2024

Introduction

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.

The docker commit command explained, with examples.

Prerequisites

docker commit Command

The 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

The docker commit command uses the following syntax:

docker commit [options] [container-id-or-name] [image-name]:[tag]

The [tag] part of the command is optional. If you create an image without a tag, Docker defaults to latest.

The command accepts the options listed in the table below:

OptionDescription
-a, --authorInclude the name of the image author.
-c, --changeApply a Dockerfile instruction to the new image. Supported instructions are CMD, ENTRYPOINT, ENV, EXPOSE, LABEL, ONBUILD, USER, VOLUME, and WORKDIR.
-m, --messageInclude a custom message with the image.
-p, --pausePause the container during the commit operation. If the option is not specified, the command assumes the value is true.

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:

docker commitdocker push
FunctionCreates an image from a container and saves it locally.Uploads a local image to a remote registry.
Basic Syntaxdocker commit [container] [image]:[tag]docker push [registry]/[image]:[tag]
Other Aliasesdocker container commitdocker image push
Use CaseHelps 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 commit:

1. Use 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.

A docker command to run Ubuntu image in a container.

2. Modify the image according to your needs. The following example uses APT to install Nmap, a network discovery and security auditing tool:

apt install nmap -y

The command downloads the necessary packages and installs them inside the running container.

Installing Nmap in Ubuntu Docker container.


3. Once you finish with the modifications, exit the container:

exit

The container stops, and the terminal returns to the operating system's shell.

Exiting a container shell in Docker.

4. List all Docker containers on the system:

docker ps -a

5. Locate and copy the ID of the container you modified.

Finding the Ubuntu container ID by listing all Docker containers.

6. Commit the changes to a new image by typing:

docker commit [container-id] [new-image-name]

For example, the command below creates an image named ubuntu-with-nmap:

docker commit c624caff45a8 ubuntu-with-nmap

If the operation is successful, the output displays the sha256 hash value of the image ID.

Using docker commit to commit a container contents to a new Docker image.

7. Verify that the image has been created by listing the locally available images:

docker images
sudo docker images shows Docker commit was successful.

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.

Conclusion

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.

Was this article helpful?
YesNo
Marko Aleksic
Marko Aleksić is a Technical Writer at phoenixNAP. His innate curiosity regarding all things IT, combined with over a decade long background in writing, teaching and working in IT-related fields, led him to technical writing, where he has an opportunity to employ his skills and make technology less daunting to everyone.
Next you should read
Docker ADD vs COPY: What are the Differences?
January 25, 2024

ADD and COPY are Docker commands for copying files and directories to a Docker image using a Dockerfile. Although there are...
Read more
How to SSH into a Running Docker Container and Run Commands
December 19, 2023

This knowledge base article explains how to SSH into a running Docker container. Docker exec and docker...
Read more
How to Create Docker Image with Dockerfile
October 23, 2019

A Dockerfile is a script with instructions on how to build a Docker image. These instructions are, in fact, a group of commands...
Read more
How to List / Start / Stop Docker Containers
May 27, 2019

A Docker container uses an image of a preconfigured operating system environment. Images are often a...
Read more