LinuxCommandLibrary

docker-commit

Create a new image from a container's changes

TLDR

Create an image from a specific container

$ docker commit [container] [image]:[tag]
copy

Apply a CMD Dockerfile instruction to the created image
$ docker commit [[-c|--change]] "CMD [command]" [container] [image]:[tag]
copy

Apply an ENV Dockerfile instruction to the created image
$ docker commit [[-c|--change]] "ENV [name]=[value]" [container] [image]:[tag]
copy

Create an image with a specific author in the metadata
$ docker commit [[-a|--author]] "[author]" [container] [image]:[tag]
copy

Create an image with a specific comment in the metadata
$ docker commit [[-m|--message]] "[comment]" [container] [image]:[tag]
copy

Create an image without pausing the container during commit
$ docker commit [[-p|--pause]] [false] [container] [image]:[tag]
copy

Display help
$ docker commit --help
copy

SYNOPSIS

docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]

PARAMETERS

-a, --author string
    Set the author for the committed image (e.g., 'John Doe ').

-c, --change list
    Apply Dockerfile instructions to the new image (e.g., CMD ["new-command"], EXPOSE 8080, ENV VAR=value).

-m, --message string
    Provide a commit message for the new image, similar to a Git commit message.

-p, --pause
    Pause the container during the commit process (default is true). Pausing ensures data consistency.

-s, --squash
    Squash all new layers into a single new layer (experimental feature).

DESCRIPTION

The docker commit command creates a new Docker image from the changes made to an existing container. It essentially captures the current state of a running or stopped container, including any modifications to its filesystem, configuration, or installed software, and saves it as a new image layer. This command is often used for debugging, quickly saving a working state, or for creating a base image from a manually configured container. However, for reproducible and robust image building, the use of a Dockerfile with docker build is highly recommended. The docker commit operation adds a new layer on top of the container's base image, preserving the history of changes made within the container. It's a quick way to package changes, but lacks the transparency and automation of a proper build process.

CAVEATS

While docker commit is useful for quick snapshots or debugging, it is not recommended for building production-ready images due to its lack of reproducibility. Changes made with docker commit are opaque and cannot be easily tracked, versioned, or audited, unlike changes defined in a Dockerfile. Prefer using docker build with a Dockerfile for any image intended for deployment, collaboration, or long-term maintenance.

IMAGE LAYERS AND REPRODUCIBILITY

When you commit a container, Docker creates a new read-only layer containing all the changes made to the container's filesystem. This new layer is then added on top of the original image layers. While this process is efficient in terms of storage and quick for snapshots, it creates a non-reproducible artifact. The exact steps leading to the committed image are not recorded within the image itself, making it difficult to rebuild the image identically or to understand the provenance of its contents. This lack of transparency and reproducibility is a primary reason why Dockerfiles are universally favored for serious image building.

HISTORY

The docker commit command has been a core part of Docker since its early days, serving as one of the initial methods for creating new images. Its primary role in image creation diminished significantly with the widespread adoption and maturation of Dockerfiles, which offer a more declarative, reproducible, and transparent way to define image builds. Today, it is more commonly used for ad-hoc image capturing, debugging, or personal experimentation rather than for formal, automated image build pipelines.

SEE ALSO

docker build(1), Dockerfile(5), docker save(1), docker push(1)

Copied to clipboard