Docker Image Command Reference

Manage Docker images: list, build, remove, inspect, and more

Syntax

docker image COMMAND

The docker image command provides a set of subcommands for managing Docker images, including creating, listing, inspecting, and removing images.

Docker images are the basis of containers. An image is a read-only template with instructions for creating a Docker container. Images contain the application code, libraries, dependencies, tools, and other files needed for your application to run.

The docker image command provides a set of subcommands for managing your Docker images. These commands allow you to build, list, inspect, tag, push, pull, and remove images, among other operations.

Available Commands

The docker image command includes the following subcommands:

Command Description
docker image build Build an image from a Dockerfile (shorthand: docker build)
docker image history Show the history of an image
docker image import Import the contents from a tarball to create a filesystem image
docker image inspect Display detailed information on one or more images
docker image load Load an image from a tar archive or STDIN
docker image ls List images (shorthand: docker images)
docker image prune Remove unused images
docker image pull Pull an image or a repository from a registry (shorthand: docker pull)
docker image push Push an image or a repository to a registry (shorthand: docker push)
docker image rm Remove one or more images (shorthand: docker rmi)
docker image save Save one or more images to a tar archive
docker image tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE (shorthand: docker tag)

In addition to the docker image commands, there are shorthand commands for the most commonly used operations, such as docker build, docker pull, and docker push.

Common Image Commands

docker image ls

Lists the Docker images available on your system.

docker image ls [OPTIONS] [REPOSITORY[:TAG]]

Common options:

  • -a, --all: Show all images (default hides intermediate images)
  • --digests: Show digests
  • -f, --filter: Filter output based on conditions provided
  • --format: Format output using a custom template
  • --no-trunc: Don't truncate output
  • -q, --quiet: Only show image IDs

Example:

docker image ls --filter "reference=node:*" --format "{{.Repository}}:{{.Tag}}"
docker image build

Builds an image from a Dockerfile.

docker image build [OPTIONS] PATH | URL | -

Common options:

  • -t, --tag: Name and optionally a tag in the 'name:tag' format
  • -f, --file: Name of the Dockerfile (Default is 'PATH/Dockerfile')
  • --no-cache: Do not use cache when building the image
  • --pull: Always attempt to pull a newer version of the image
  • --build-arg: Set build-time variables
  • --target: Set the target build stage to build
  • --platform: Set platform if server is multi-platform capable

Example:

docker image build -t myapp:1.0 --build-arg VERSION=1.0 .
docker image tag

Creates a tag TARGET_IMAGE that refers to SOURCE_IMAGE.

docker image tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

Example:

docker image tag myapp:latest myregistry.example.com/myapp:v1.0.0
docker image inspect

Displays detailed information on one or more images.

docker image inspect [OPTIONS] IMAGE [IMAGE...]

Common options:

  • -f, --format: Format output using a custom template

Example:

docker image inspect --format '{{.Config.Labels}}' myapp:latest
docker image history

Shows the history of an image, displaying the layers that make up the image.

docker image history [OPTIONS] IMAGE

Common options:

  • --format: Format output using a custom template
  • --no-trunc: Don't truncate output
  • -q, --quiet: Only show image IDs

Example:

docker image history --no-trunc myapp:latest
docker image rm

Removes one or more images.

docker image rm [OPTIONS] IMAGE [IMAGE...]

Common options:

  • -f, --force: Force removal of the image
  • --no-prune: Do not delete untagged parents

Example:

docker image rm -f myapp:latest
docker image prune

Removes unused images.

docker image prune [OPTIONS]

Common options:

  • -a, --all: Remove all unused images, not just dangling ones
  • -f, --force: Do not prompt for confirmation
  • --filter: Filter images based on provided conditions

Example:

docker image prune -a --filter "until=24h"
docker image save/load

Save and load images to and from a tar archive.

docker image save -o myimages.tar image1 [image2 ...]
docker image load -i myimages.tar

Common options:

  • -o, --output: Write to a file, instead of STDOUT (for save)
  • -i, --input: Read from tar archive file, instead of STDIN (for load)

Example:

docker image save -o myapp-backup.tar myapp:latest
docker image load -i myapp-backup.tar

Examples

Listing Images

List all images with different formatting options:

# List all images
docker image ls

# List all images, including intermediate layers
docker image ls -a

# List images with custom formatting
docker image ls --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

# List only image IDs
docker image ls -q

# List images filtered by reference
docker image ls --filter "reference=node:*"

These commands demonstrate various ways to list and filter Docker images on your system.

Building Images

Build images with different options:

# Build an image from the current directory
docker image build -t myapp:latest .

# Build using a specific Dockerfile
docker image build -f Dockerfile.prod -t myapp:prod .

# Build with build arguments
docker image build --build-arg VERSION=1.0 --build-arg ENV=production -t myapp:1.0 .

# Build targeting a specific stage in a multi-stage build
docker image build --target build-stage -t myapp:build .

# Build with no cache
docker image build --no-cache -t myapp:fresh .

These commands show how to build Docker images with various options like tagging, build arguments, and stage targeting.

Tagging Images

Tag images for different purposes:

# Tag for a specific version
docker image tag myapp:latest myapp:1.0.0

# Tag for a registry
docker image tag myapp:latest registry.example.com/myapp:latest

# Multiple tags for the same image
docker image tag myapp:latest myapp:stable
docker image tag myapp:latest myapp:current

These commands demonstrate how to create different tags for Docker images, which is useful for versioning and preparing for registry pushes.

Inspecting Images

Inspect images to view their metadata:

# Inspect an image
docker image inspect myapp:latest

# Format the output to show only specific information
docker image inspect --format '{{.Config.Env}}' myapp:latest

# View the image's labels
docker image inspect --format '{{json .Config.Labels}}' myapp:latest | jq

# Check the image's exposed ports
docker image inspect --format '{{.Config.ExposedPorts}}' myapp:latest

These commands show how to inspect Docker images and extract specific information from their metadata.

Managing Image Storage

Manage disk space by removing and pruning images:

# Remove a specific image
docker image rm myapp:oldversion

# Force remove an image being used by a container
docker image rm -f myapp:latest

# Remove multiple images
docker image rm myapp:v1 myapp:v2 myapp:v3

# Remove all dangling images (untagged images)
docker image prune

# Remove all unused images (not just dangling ones)
docker image prune -a

# Remove images older than a certain time
docker image prune --filter "until=24h"

These commands demonstrate how to manage Docker image storage by removing individual images or pruning unused images.

Exporting and Importing Images

Save and load images for transfer or backup:

# Save a single image to a tar file
docker image save -o myapp.tar myapp:latest

# Save multiple images to a tar file
docker image save -o myimages.tar myapp:latest myapp:stable

# Load an image from a tar file
docker image load -i myapp.tar

# Save an image and compress it
docker image save myapp:latest | gzip > myapp.tar.gz

# Load a compressed image
gunzip -c myapp.tar.gz | docker image load

These commands show how to export Docker images to tar archives and import them, which is useful for transferring images between systems without using a registry.

Best Practices

  • Use specific tags: Avoid using the latest tag for production deployments. Use specific version tags or image digests instead for better reproducibility.
  • Clean up regularly: Use docker image prune regularly to remove unused images and free up disk space.
  • Use multi-stage builds: Use multi-stage builds to create smaller, more efficient images by separating build and runtime environments.
  • Use .dockerignore: Create a .dockerignore file to prevent unnecessary files from being included in your build context, which can speed up builds and reduce image size.
  • Tag purposefully: Use meaningful tags that convey information about the image's content, version, or purpose.
  • Use build arguments: Utilize build arguments to make your Dockerfiles more flexible and reusable.
  • Pin base image versions: Use specific versions of base images in your Dockerfile (e.g., FROM node:18.12.1 instead of FROM node:latest) to ensure reproducible builds.
  • Understand image layers: Be aware of how Docker's layer caching works and organize your Dockerfile instructions to maximize cache efficiency.
  • Sign your images: Consider signing your Docker images for enhanced security and to verify their authenticity.
  • Use content trust: Enable Docker Content Trust to ensure you're pulling and pushing trusted images.

Image Naming and Tags

Docker image names typically follow a format that includes a repository name and an optional tag:

repository[:tag]

For images in Docker Hub, the repository can be a simple name like nginx or ubuntu. For images in other registries, the repository includes the registry domain:

registry.example.com/username/repository[:tag]

The tag is often used to indicate the version of the image. If no tag is specified, Docker defaults to the latest tag.

Images also have a digest, which is a SHA256 hash that uniquely identifies a specific version of an image. Digests can be used instead of tags for complete reproducibility:

repository@sha256:digest

For example: ubuntu@sha256:45b23dee08af5e43a7fea6c4cf9c25ccf269ee113168c19722f87876677c5cb2

Notes and Limitations

  • Docker images are stored in a layered filesystem, where each layer corresponds to an instruction in the Dockerfile.
  • Images can be large, especially if they contain unnecessary files or if their layers aren't optimized.
  • When removing an image with docker image rm, you might encounter errors if containers are using the image. You'll need to stop and remove those containers first or use the -f flag to force removal.
  • The docker image prune -a command can remove a significant amount of disk space, but be cautious as it removes all unused images.
  • When using docker image save and docker image load, the entire image with all its layers is saved or loaded, which can be time-consuming for large images.
  • Docker Content Trust is not enabled by default and requires additional setup.
  • Multi-architecture images require additional tooling like BuildKit to build and manage.
  • Some Docker commands may behave differently depending on the Docker version and configuration.

Related Commands

docker build

Build an image from a Dockerfile.

docker push/pull

Push or pull images to and from registries.

Layer Caching

Understanding how Docker layer caching works for efficient builds.

Multi-stage Builds

Create smaller, more efficient images using multi-stage builds.
Reference Index
Docker Push/Pull Commands

On This Page

Try Our Tools

Optimize your Docker image builds.

Image Size Calculator

Related Tutorials