Docker images are the read-only packages used to create containers. They contain an application, its dependencies, and the filesystem layers needed to run it. A container is a running or stopped instance created from an image.
This guide explains how to pull Docker images, run them as containers, list and inspect local images, check image size and layers, remove unused images, and troubleshoot common image commands.
Docker image vs. Docker container
An image is a packaged template. A container is an instance created from that template.
| Docker object | What it means | Common commands |
|---|---|---|
| Image | Read-only package used to create containers | docker pull, docker image ls, docker image rm |
| Container | Runnable instance of an image | docker run, docker ps, docker stop |
| Volume | Persistent data stored outside the container’s writable layer | docker volume ls, docker volume inspect |
Deleting an image does not automatically delete a container that was created from it. Likewise, deleting a container does not automatically remove the image. Treat these as separate resources.
Check whether Docker is running
Before downloading or running an image, verify that the Docker CLI can communicate with the daemon:
docker version
docker infoIf the command cannot connect to the daemon, start Docker Desktop or the Docker service on your operating system before continuing.
How to pull a Docker image
Use docker pull to download an image from a registry such as Docker Hub:
docker pull nginxWhen no tag is specified, Docker uses the latest tag by default:
docker pull nginx:latestFor repeatable deployments, prefer a specific version instead of relying on latest:
docker pull nginx:1.27An image can also be pulled by digest when you need an exact immutable image reference:
docker pull nginx@sha256:IMAGE_DIGESTDocker downloads the image layers and stores them in the local image cache. After the pull completes, list the local images:
docker image lsThe modern management-command form is docker image pull. The shorter docker pull command is an alias:
docker image pull nginx
docker pull nginxPull an image for a specific platform
Multi-platform images can contain variants for architectures such as AMD64 and ARM64. Request a specific platform when needed:
docker pull --platform linux/amd64 nginx
docker pull --platform linux/arm64 nginxUse the platform that matches the host or the deployment target. Pulling the wrong architecture can lead to an “exec format error” when the container starts.
How to list Docker images
The most common command for listing local images is:
docker imagesThe equivalent management-command form is:
docker image lsThe output normally includes the repository, tag, image ID, creation time, and virtual size:
REPOSITORY TAG IMAGE ID CREATED SIZE
nginx 1.27 abc123def456 2 weeks ago 192MB
alpine latest 4bcff639e11e 3 weeks ago 7.8MBList images for one repository:
docker image ls nginxFilter by repository or tag:
docker image ls --filter reference="nginx:1.27"Show intermediate and dangling images too:
docker image ls --allDangling images usually appear with a repository and tag of <none>. They are often leftover layers from builds, but check that they are not needed before removing them.
Check Docker image size and disk usage
The size shown by docker image ls is useful for a quick comparison. For an overview of Docker’s reclaimable disk space, use:
docker system dfTo see detailed space usage:
docker system df --verboseImage size is made up of filesystem layers. Images can share layers, so the total displayed size of several images is not always the same as the actual disk space consumed.
Inspect an image
Use docker image inspect to view the image’s configuration, architecture, entrypoint, environment, root filesystem layers, and digest:
docker image inspect nginx:1.27Extract one property with a Go template:
docker image inspect --format='{{.Architecture}}' nginx:1.27
docker image inspect --format='{{.Os}}' nginx:1.27
docker image inspect --format='{{json .Config.Cmd}}' nginx:1.27Check the image’s layer history:
docker image history nginx:1.27Image history helps identify which Dockerfile instructions created large layers. It is useful when an image is unexpectedly large or builds slowly.
How to run a Docker image as a container
Use docker run to create and start a new container from an image:
docker run nginxFor a practical web-server example, run it in the background, give it a name, and publish port 8080 on the host to port 80 in the container:
docker run -d --name my-nginx -p 8080:80 nginx:1.27Open http://localhost:8080 to test the service. Check the container with:
docker ps
docker ps -aUseful docker run options
| Option | Purpose | Example |
|---|---|---|
-d | Run in the background | docker run -d nginx |
--name | Assign a readable container name | --name my-nginx |
-p | Publish a host port | -p 8080:80 |
-e | Set an environment variable | -e APP_ENV=production |
-v | Mount a volume or host directory | -v app-data:/data |
--rm | Remove the container after it exits | --rm alpine echo done |
--pull | Control whether Docker pulls the image | --pull=always |
A short-lived test container is often convenient with --rm:
docker run --rm alpine:latest echo "Docker is working"Do not use --rm for a service whose container logs or stopped state you need to inspect later.
Understand docker pull vs. docker run
docker pull downloads an image into the local cache. It does not create a container.
docker run creates and starts a new container. If the requested image is missing locally, Docker normally pulls it first:
docker pull nginx:1.27
docker run -d --name my-nginx -p 8080:80 nginx:1.27You can control the implicit pull behavior:
docker run --pull=always nginx:1.27
docker run --pull=missing nginx:1.27
docker run --pull=never nginx:1.27missing uses the local cache when available, always checks the registry before creating the container, and never fails if the image is not already present.
Tag a local image
A tag gives a local image a repository and version label. Tag an existing image with:
docker image tag SOURCE_IMAGE:TAG TARGET_IMAGE:TAGFor example:
docker image tag nginx:1.27 myregistry.example.com/team/nginx:1.27
docker image lsAdding a tag does not copy the image. It creates another reference to the same image ID. This is commonly used before pushing an image to a private registry.
Remove one Docker image
Remove an image by repository and tag:
docker image rm nginx:1.27You can also use the image ID:
docker image rm IMAGE_IDIf a container still references the image, Docker may refuse to remove it. Inspect the containers first:
docker ps -a --filter ancestor=nginx:1.27Remove the container only when you are sure it is no longer needed:
docker rm container_name
docker image rm nginx:1.27Removing an image tag may not immediately free all disk space if another tag or container still references the same underlying layers.
Remove unused Docker images safely
Start with the least destructive cleanup command. Remove dangling images only:
docker image pruneDocker asks for confirmation before removing them. Preview your current image and disk state first:
docker image ls --all
docker system dfTo remove all images that are not referenced by any container, use:
docker image prune --allThis is more aggressive than the default prune command. It can delete older tagged images that are not currently used by a container, so verify that you can pull or rebuild them again.
Limit pruning by age with a filter:
docker image prune --all --filter "until=240h"Use --force only when you intentionally want to skip the confirmation prompt:
docker image prune --forceDo not confuse docker image prune with docker system prune. The system command can also remove stopped containers, unused networks, and other resources. It has a wider impact.
Save and load an image without a registry
Export an image to a tar archive:
docker image save -o nginx-1.27.tar nginx:1.27Copy the archive to another machine and load it:
docker image load -i nginx-1.27.tar
docker image lsThis is useful for an offline server or a network-restricted environment. The archive can be large, so check available disk space first.
Troubleshoot common Docker image problems
“Unable to find image” or “pull access denied”
Check the image name and tag carefully:
docker pull repository/image:tagPrivate images require authentication:
docker login
docker pull private-registry.example.com/team/app:1.0Do not place passwords directly in shell history or command arguments. Use Docker’s supported login flow and credential storage.
“No such image” when using docker run
Confirm the local image name and tag:
docker image ls
docker image inspect repository/image:tagThen either pull the image or correct the name passed to docker run.
Docker pull is slow
Large images contain more layers and take longer to download. Check the image size, your network connection, registry rate limits, and daemon proxy configuration. Avoid repeatedly pulling latest in scripts when a pinned version is sufficient.
Exec format error after docker run
This often indicates an architecture mismatch. Check the image and host architecture:
docker version
docker image inspect --format='{{.Os}}/{{.Architecture}}' IMAGE:TAGPull or build the correct platform variant, or explicitly choose a supported platform with --platform.
Best practices for managing Docker images
- Use explicit version tags for production deployments.
- Use image digests when exact reproducibility matters.
- Review image provenance and scan images before production use.
- Keep application images small with multi-stage Dockerfiles and an appropriate base image.
- Use
docker system dfbefore cleanup. - Remove unused images regularly, but do not prune blindly on build or production hosts.
- Use named volumes for data that must survive container replacement.
- Do not store passwords or API keys in image layers.
Quick Docker image command reference
| Task | Command |
|---|---|
| Download an image | docker pull IMAGE:TAG |
| List images | docker image ls |
| List all images | docker image ls -a |
| Inspect an image | docker image inspect IMAGE |
| Show image layers | docker image history IMAGE |
| Run an image | docker run IMAGE |
| Tag an image | docker image tag SOURCE TARGET |
| Remove an image | docker image rm IMAGE |
| Remove dangling images | docker image prune |
| Remove all unused images | docker image prune -a |
| Show Docker disk usage | docker system df |
| Save an image | docker image save -o FILE IMAGE |
| Load an image | docker image load -i FILE |
Conclusion
Use docker pull to download an image, docker image ls to list local images, and docker run to create a container from an image. Use docker image inspect and docker image history when you need more detail. Before deleting anything, check which containers reference the image and review disk usage. Start with docker image prune for dangling images and use broader cleanup commands only when you understand their impact.