Turn a Tested Container into a Docker Image with docker commit

You will finish with a new local Docker image made from an existing container, including 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

Checkpoint: write down EXAMPLE_CONTAINER and the image tag you plan to create. This prevents a later shell command from being aimed at the wrong service.

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}}'

Look for passwords, tokens, private keys and generated data in both the filesystem and environment. Remove sensitive material from the container, or use a clean container and inject secrets at runtime. Treat the resulting image as sensitive until you have inspected its layers.

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. The pause can briefly affect a running service, so schedule this during a suitable window and do not use --no-pause merely to hide a delay. With --no-pause, concurrent writes can leave the captured state inconsistent.

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

Replace the path in the test with a file or command that proves your own change. The --force removal stops the temporary test container first. It does not remove the image you just created.

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

Image removal is destructive for that local image reference and may remove untagged layers. Do not run it until you have confirmed the repository and tag. The original container remains available, but any changes made only inside it are not reconstructed by removing the image.

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 are treating a volume as part of the image, using latest when an immutable tag is needed, forgetting that a commit can pause production processes, and assuming a successful image creation also means the application starts correctly. Verify the image with a temporary run before replacing a deployment.