Docker images are at the heart of containerized applications, bundling everything from the OS base layers to your app code and dependencies. But sometimes, you may want to inspect the contents of a Docker image — to debug, verify files, or simply understand what’s inside.
In this post, we’ll explore multiple ways to view the contents of a Docker image, both with and without running a container.
🧭 Why View Image Contents?
You might want to inspect an image to:
- Confirm a file or binary is included
- Review installed packages or environment variables
- Explore the file structure before deployment
- Debug build or runtime issues
🐳 Option 1: Run a Container and Explore with a Shell
The most direct way is to run the image interactively and explore the filesystem.
docker run -it --rm IMAGE_NAME bash
Or if the image doesn’t have bash:
docker run -it --rm IMAGE_NAME sh
Once inside, use commands like:
ls, cat, find, env, which, less
to browse and inspect the filesystem.
🔍 Option 2: Use docker create and docker cp
If you don’t want to start the container fully, you can create it, copy files out, and inspect locally.
Step 1: Create a container from the image
container_id=$(docker create IMAGE_NAME)
Step 2: Copy files from the container
docker cp $container_id:/app ./local_app_folder
Step 3: Clean up
docker rm $container_id
This allows you to extract specific directories or files without running the container.
🗂 Option 3: Dive – A Powerful CLI Tool
Dive is a third-party tool that lets you analyze Docker image layers visually and see what’s added in each layer.
Install Dive:
brew install dive # macOS
sudo apt install dive # Ubuntu (via apt repo)
Use it:
dive IMAGE_NAME
Dive shows:
- Layer-by-layer changes
- File size deltas
- Efficiency hints
- What files came from which instruction
🧱 Option 4: Inspect with docker image inspect
While it won’t show actual files, this gives metadata about the image.
docker image inspect IMAGE_NAME
You’ll see:
- Environment variables
- Entry point and command
- Working directory
- Exposed ports
- Labels and more
📦 Option 5: Extract the Image Filesystem
You can export the full image as a tarball and inspect it manually.
Step 1: Save the image
docker save IMAGE_NAME > image.tar
Step 2: Extract it
mkdir extracted && tar -xf image.tar -C extracted
Step 3: Explore layers
Inside the extracted folder, you’ll see multiple layer tar files. You can untar and explore them:
tar -xf layer.tar
This is a low-level method, but useful for deep inspection and automation.
🧠 Summary of Methods
| Method | Description | Best For |
|---|---|---|
docker run -it | Run and explore interactively | Quick browsing |
docker create + cp | Copy files without starting | File extraction |
dive | Visual layer analysis | Optimization & audit |
docker image inspect | Show image metadata | Configuration check |
docker save | Extract raw image filesystem | Deep inspection or archiving |
🧭 Conclusion
Whether you need to check for a missing file, debug an image layer, or validate what goes into your Docker builds — there are multiple ways to inspect Docker image contents. Choose the method that fits your workflow and level of depth needed.