Read a Docker Container's Filesystem Changes with docker diff

You will finish with a short, repeatable way to see which paths Docker records as added, changed or deleted inside a container. The command is read-only, but the test setup creates a container, so allow about ten minutes and remove that test container when you are done.

This guide uses Docker CLI 29.8.1 from the installed docker-ce-cli package. You need a working Docker client and access to a Docker daemon. The examples use the alpine:latest image; if it is not already available, Docker may need to pull it from a registry.

1. Check the installed command

Start by confirming the client version and the command syntax. These are ordinary read-only checks and do not need elevated privileges:

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker diff --help
Usage:  docker diff CONTAINER

Inspect changes to files or directories on a container's filesystem

The installed manpage documents docker diff CONTAINER and identifies it as an alias for docker container diff CONTAINER. There are no documented options on this command. That is a useful boundary: choose the container precisely, then inspect its result.

2. Choose the container by name or ID

List containers so you can copy an exact name or ID. This does not change any container:

$ docker ps -a --format 'table {{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}'
CONTAINER ID   NAMES        IMAGE          STATUS
1fdfd1f54c1b   web-test     nginx:latest   Up 2 minutes
9c4a7b2d1e0f   batch-test   alpine:latest  Exited (0) 4 minutes ago

Use the full or shortened ID, or a container name. Replace CONTAINER_NAME below with a value from your own output. Do not confuse an image name such as nginx:latest with a container name. The command accepts a container, not an image.

If you are examining a production container, record the exact name and confirm it with the owner before continuing. The inspection itself does not write to the container, but the paths may contain application data, temporary files or logs that should not be copied into an issue or chat without review.

3. Inspect the recorded filesystem changes

Run the command with the selected container. This is a read-only inspection and normally needs no sudo when your account can access Docker:

$ docker diff CONTAINER_NAME
C /dev
C /run
A /run/example.pid
A /var/log/example.log
C /var/lib/example
D /var/lib/example/old-cache.db

Docker uses three change markers:

• A means a file or directory was added.
• C means a file or directory was changed.
• D means a file or directory was deleted.

The paths are inside the container filesystem and are normally listed from the root, so /var/log/example.log is not a path on your host. A changed directory does not by itself explain which child caused the change. Read the more specific entries below it and compare them with the container's startup and runtime behaviour.

4. Understand what the result means

docker diff reports changes to files and directories since the container was created. It is not a complete directory listing, a content diff and not a comparison against the current image tag. A path marked C tells you that Docker recorded a change, but not the exact bytes or the process that made it.

Some changes are expected. Applications commonly create PID files, caches, sockets and logs at startup. Runtime-managed paths such as parts of /dev or /run can also produce noise. Treat an unexpected path as a lead for investigation, not as proof of compromise or misconfiguration.

For a closer look at one path, use a separate read-only command such as:

$ docker exec CONTAINER_NAME sh -c 'ls -ld -- /var/log/example.log 2>/dev/null || true'
-rw-r--r--    1 root     root             0 Sep 23 10:15 /var/log/example.log

This extra command requires the container to be running and requires a suitable shell inside it. It is not part of docker diff, and a missing shell or stopped container is a limitation of the follow-up check, not a failure of the original inspection.

5. Make a disposable test change

If you need to learn the markers without touching an existing workload, create a clearly named test container. This changes Docker state and may pull an image, so do it only where that is acceptable:

$ docker run --name docker-diff-demo -d alpine:latest sh -c 'sleep 300'
4c2d7e8f6a1b...
$ docker exec docker-diff-demo sh -c 'echo test > /tmp/docker-diff-demo.txt; rm /tmp/docker-diff-demo.txt; mkdir /tmp/docker-diff-demo-dir'
$ docker diff docker-diff-demo
A /tmp/docker-diff-demo-dir

The deleted file may not appear in the final output because it was created and removed after the container started. That is a useful reminder that the result is a current change view, not an audit log of every historical event. Exact output can also include runtime noise, so focus on the paths you intentionally changed.

Clean up the test container after you have finished checking it:

$ docker rm --force docker-diff-demo
docker-diff-demo

6. Diagnose the common failures

An error such as No such container means the name or ID does not identify a container visible to the selected daemon. Rerun docker ps -a, check spelling and check whether your shell is using the expected Docker context. Do not replace the name with an image name.

If Docker reports a daemon connection problem, the client is working but cannot reach its configured daemon. Check the daemon's service status and your account's Docker access according to your system policy. Using sudo may change which Docker socket, context and credentials are used, so treat it as an administrative choice, not a general repair.

An empty result is valid. It means Docker found no recorded changes to list for that container, not that the container contains no files. A container can also exit before you inspect it, so compare its status and choose a stable inspection point when troubleshooting.