Turn a Container into an Image with docker commit

You tweaked a container until it worked, and now you want to keep that state as an image. docker container commit does exactly that, with a documented configuration change where needed. The examples use Docker Community Edition CLI 29.8.1 from package docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble. Allow about ten minutes if the container is already in a known-good state.

You need access to the Docker daemon and a container whose changes you have checked. Ordinary Docker access is enough when your account is already authorised to use the daemon. If it is not, use your site's approved privilege method, such as sudo docker ...; membership of the Docker group is effectively privileged access to the host.

1. Identify the source container

List running containers and copy the ID or name of the one you intend to capture:

$ docker ps
CONTAINER ID   IMAGE          COMMAND       CREATED        STATUS        PORTS     NAMES
2626d6c28708   parish:latest  ...           ...            Up ...                   parish

The command accepts a container ID or name. Use a specific value rather than copying the first row from a long listing. If the container has stopped, include all containers:

$ docker ps -a --filter name=EXAMPLE_CONTAINER

2. Check what will and will not be captured

docker container commit captures changes in the container's writable filesystem and can apply a small set of image configuration instructions. It does not include data held in mounted volumes. A database directory, upload store or bind mount therefore needs its own backup or migration plan.

Inspect mounts and the current configuration before committing:

$ docker inspect EXAMPLE_CONTAINER --format '{{json .Mounts}}'
$ docker inspect EXAMPLE_CONTAINER --format '{{json .Config.Env}}'

3. Create the image with a clear tag

Run the commit with an explanatory message and, optionally, an author. Replace every uppercase placeholder:

$ docker container commit \
    --message='Installed and tested Apache configuration' \
    --author='Example Operator <[email protected]>' \
    EXAMPLE_CONTAINER example/apache-tested:2026-09-23

On success, Docker prints the new image ID, usually as a long hexadecimal value:

sha256:EXAMPLE_IMAGE_ID

The repository and tag must use Docker's valid image naming rules. Use a meaningful version or date instead of relying only on latest. A commit is not pushed to a registry automatically; it exists in the local Docker daemon until you explicitly run docker push.

By default, Docker pauses the container while creating the image. That reduces the chance of filesystem changes racing with the commit.

4. Verify the new image

Confirm that the tag resolves locally and check its size and creation time:

$ docker image inspect example/apache-tested:2026-09-23 \
    --format 'ID={{.Id}} Created={{.Created}} Size={{.Size}}'
ID=sha256:EXAMPLE_IMAGE_ID Created=... Size=...
$ docker image ls example/apache-tested:2026-09-23

Check the configuration captured by the image. The exact output depends on the source container:

$ docker image inspect example/apache-tested:2026-09-23 \
    --format 'Entrypoint={{json .Config.Entrypoint}} Cmd={{json .Config.Cmd}} Env={{json .Config.Env}}'

For a stronger check, start a temporary container from the new image and inspect the change. This creates a new container, so remove that temporary container after the test:

$ docker run --name commit-check --detach example/apache-tested:2026-09-23
$ docker exec commit-check sh -c 'test -f /etc/apache2/apache2.conf'
$ docker rm --force commit-check
commit-check

5. Apply a small configuration change while committing

The --change option applies one Dockerfile instruction to the created image. Supported instructions on the current Docker reference are CMD, ENTRYPOINT, ENV, EXPOSE, LABEL, ONBUILD, USER, VOLUME and WORKDIR. For example, add an environment value without changing the source container:

$ docker container commit \
    --change='ENV DEBUG=true' \
    --message='Capture tested debug configuration' \
    EXAMPLE_CONTAINER example/app-debug:2026-09-23
$ docker image inspect example/app-debug:2026-09-23 \
    --format '{{json .Config.Env}}'

For JSON-array commands, quote the whole instruction so the shell does not split it:

$ docker container commit \
    --change='CMD ["apachectl", "-DFOREGROUND"]' \
    EXAMPLE_CONTAINER example/apache-foreground:2026-09-23

This changes the new image's configuration only. It does not rewrite the original container. If the new image is wrong, delete that image tag after checking it is not needed:

$ docker image rm example/apache-tested:2026-09-23

6. Choose the next step deliberately

Keep the image local for a short-lived investigation, or tag and push it only after reviewing its contents and access controls. If another machine must reproduce the result, write the changes into a Dockerfile and build from a clean, declared base image. That preserves the commands, inputs and review history that a commit cannot explain.

Common traps

• Treating a volume as part of the image. Committed images hold the writable filesystem, not mounted data.
• Using latest when you need an immutable tag. Pick a version or date.
• Forgetting the pause. A commit can pause production processes.
• Assuming a built image means a working app. Verify the image with a temporary run before replacing a deployment.