# Introduction to Docker Images

> Learn what a Docker image contains, how immutable layers, Dockerfiles, tags, and digests work, and how to build safer, smaller images.

Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2020-07-07 | Updated: 2026-07-18 | Topics: [Docker](https://flaviocopes.com/tags/docker/) | Canonical: https://flaviocopes.com/docker-images/

A [Docker](https://flaviocopes.com/docker-introduction/) image is an immutable package containing an application's filesystem and the configuration needed to start it.

When you run an image, Docker creates a [container](https://flaviocopes.com/docker-containers/) with a writable layer on top. Changes made inside that container do not modify the original image.

## What is inside a Docker image?

An image contains:

- Filesystem layers with the app, runtime, libraries, and system files
- Configuration such as the default command, working directory, user, and environment variables
- Metadata describing the image

Image layers are content-addressed and can be shared between images. If two images use the same base layers, Docker only needs to store those layers once.

## How do you build an image?

You normally describe an image with a `Dockerfile`.

Here is a small Node.js example:

```dockerfile
FROM node:22-bookworm-slim

WORKDIR /app

COPY package*.json ./
RUN npm ci --omit=dev

COPY . .

USER node

CMD ["node", "server.js"]
```

Build it from the directory containing the `Dockerfile`:

```sh
docker build -t notes-api:1.0 .
```

The final dot is the build context. Docker can access files in that directory when processing `COPY` instructions.

Add a `.dockerignore` file so the build context does not include files such as `.git`, local dependencies, logs, or secrets.

List the images stored locally:

```sh
docker image ls
```

Then start a container from the image:

```sh
docker run --name notes-api -p 3000:3000 notes-api:1.0
```

## What are tags and digests?

In `notes-api:1.0`, `1.0` is a tag. Tags are readable names, but they are mutable: a registry can make the same tag point to a different image later.

A digest identifies image content:

```text
node@sha256:...
```

Use a digest when you need a build to select the exact same base image every time. Remember that a pinned digest does not receive security fixes automatically. Update it deliberately and rebuild regularly.

A tag can also refer to a multi-platform image. Docker chooses the matching image for the host's operating system and CPU architecture from its manifest.

## Where are images stored?

Images can stay in the local image store or be pushed to a registry.

[Docker Hub](https://hub.docker.com/) hosts public and private images. The [official Node.js image](https://hub.docker.com/_/node), for example, provides several Node.js versions and base operating systems.

Other services and private deployments can provide compatible registries too.

Pull an image with:

```sh
docker pull node:22-bookworm-slim
```

## How do you choose and build safer images?

Start with a trusted base image that contains only what the application needs. Smaller images download faster and usually contain fewer packages that need security updates.

Good defaults include:

- Use a specific version tag instead of `latest`
- Rebuild often to include current base-image and dependency fixes
- Use multi-stage builds when build tools are not needed at runtime
- Run the final application as a non-root user
- Never copy secrets, credentials, or a local `.env` file into the image
- Scan images and their dependencies before deployment
- Build and test images in CI

Order `Dockerfile` instructions so stable dependency-installation layers come before frequently changing source code. This lets Docker reuse its build cache.

Picking a base image affects how big your final image gets — I built a free [Docker base image size comparison](https://flaviocopes.com/tools/base-image-sizes/) that shows common choices side by side.

The official Docker guide has more detail on [image concepts](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/) and [Dockerfile best practices](https://docs.docker.com/build/building/best-practices/).