Turn a Container Snapshot into a Safe Docker Image

You will finish with a tagged Docker image made from a container's writable-layer changes, plus a verification step that proves what was captured. The examples use Docker Community Edition CLI 29.8.1 from package docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble.

Allow about fifteen minutes. You need Docker access, a container you are allowed to snapshot, and enough local image storage. The command normally needs no root shell, but your account must be allowed to use the Docker daemon. If that access is restricted, use your site's approved privilege method, such as sudo docker ..., for the individual command rather than changing daemon permissions.

1. Inspect the source container

Start with a read-only inventory. Use the exact container name or ID in the later command:

$ docker ps -a --no-trunc
$ docker inspect --format 'name={{.Name}} status={{.State.Status}} image={{.Config.Image}}' CONTAINER_NAME
name=/CONTAINER_NAME status=running image=IMAGE_NAME

Replace CONTAINER_NAME and IMAGE_NAME with values from your host. Do not snapshot a similarly named container by accident. If the container contains credentials, private keys, tokens or customer data, stop and review that exposure first: a committed image can preserve them in a layer even after you delete the file in a later container step.

2. Check what a commit includes

docker commit is an alias for docker container commit. Its shape is:

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

The snapshot includes changes in the container's writable layer and can also apply selected image configuration instructions. It does not include data held in mounted volumes. If the application writes its useful state to a bind mount or named volume, inspect and back up that data separately before treating the new image as complete.

By default Docker pauses the container and its processes while it creates the commit. That reduces the chance of an inconsistent snapshot. The local command exposes --no-pause to disable that pause; avoid it for a busy application unless you have accepted the consistency risk and the application has its own safe snapshot mechanism.

3. Create the image with a new tag

Choose a new, specific tag so you can identify this snapshot without moving a tag that another deployment uses:

$ docker commit \
    --author 'Your Name <[email protected]>' \
    --message 'Captured after configuring the test service' \
    CONTAINER_NAME example/app:snapshot-2026-09-23
sha256:IMAGE_DIGEST

The returned digest is variable. Record it in the change notes. The --author and --message values are image metadata; they do not identify who can later pull or run the image.

4. Verify the result and its configuration

Resolve the tag to an image ID and inspect the metadata that matters to your use case:

$ docker image inspect example/app:snapshot-2026-09-23 \
    --format 'id={{.Id}} created={{.Created}} cmd={{json .Config.Cmd}} entrypoint={{json .Config.Entrypoint}}'
id=sha256:IMAGE_ID created=2026-09-23T... cmd=[...] entrypoint=[...]
$ docker image ls example/app --no-trunc
REPOSITORY   TAG                    IMAGE ID       CREATED          SIZE
example/app  snapshot-2026-09-23   IMAGE_ID       moments ago      SIZE

Exact IDs, timestamps and sizes vary. Check that the command, entrypoint, user, environment and working directory still make sense before running the image elsewhere. A commit is not a reproducible build record: it describes the container's current state, including changes made interactively and any accidental files left behind.

5. Add a small configuration change only when needed

The --change option applies a Dockerfile instruction to the created image. The installed manpage documents the option but not the complete instruction list, so keep changes to the documented Docker commit interface and verify them with docker image inspect. For example, adding a label records ownership without changing the container's start command:

$ docker commit \
    --change 'LABEL snapshot.reason=troubleshooting' \
    CONTAINER_NAME example/app:snapshot-labelled
sha256:IMAGE_DIGEST
$ docker image inspect example/app:snapshot-labelled \
    --format '{{index .Config.Labels "snapshot.reason"}}'
troubleshooting

For a lasting build process, put the desired configuration in a Dockerfile and build it from a controlled context. A commit is useful for preserving a debugging milestone or exporting a working container state, but it hides the sequence that produced that state.

6. Test the image without changing the source container

Run a short, harmless test using the new tag. Adapt the port, command and environment to the image rather than copying a production invocation blindly:

$ docker run --rm --name app-snapshot-check \
    example/app:snapshot-2026-09-23 \
    /usr/bin/your-health-check
health check passed

--rm removes the temporary test container when it exits. It does not remove the image or the original source container. If the image starts a long-running service by default, use a separate test name and stop it deliberately after checking logs:

$ docker run -d --name app-snapshot-check example/app:snapshot-2026-09-23
CONTAINER_ID
$ docker logs --tail 50 app-snapshot-check
$ docker rm -f app-snapshot-check

The final command is service-disrupting for the test container only. Do not reuse an existing container name, and do not run this against the source container.

7. Remove the snapshot if it is no longer needed

There is no rollback operation that changes the original container. The original remains in place unless you explicitly remove or alter it. If the test image is disposable, remove its tag after confirming that no deployment or recovery process needs it:

$ docker image rm example/app:snapshot-2026-09-23
Untagged: example/app:snapshot-2026-09-23

This removes the tag and may reclaim unreferenced layers. It does not restore files inside the source container. If another tag or container still references the same image, Docker may retain the underlying layers.