Introduction

A frequent Docker question is where the image name is defined when using a Dockerfile. The key detail is that a Dockerfile describes how to build an image, but the image name is assigned when you run docker build or through tooling such as Docker Compose or CI pipelines. Once you separate build recipe from naming, tagging and release workflows become much easier.

What Dockerfile Controls Versus What Build Command Controls

The Dockerfile controls layers, base image, copied files, environment variables, and container startup command. The image name and tag are metadata attached by the build command.

1FROM python:3.12-slim
2
3WORKDIR /app
4COPY requirements.txt .
5RUN pip install --no-cache-dir -r requirements.txt
6
7COPY . .
8EXPOSE 8000
9CMD ["python", "app.py"]

Build and assign a name with a tag:

docker build -t myorg/invoice-api:1.0.0 .

The string after -t is the repository name plus tag. If no tag is given, Docker uses latest, which is often too ambiguous for production.

Use Multiple Tags for One Build

A common release practice is to tag one image with both a version tag and a moving release channel tag. This allows pinning in production while preserving convenience for development.

1docker build \
2  -t myorg/invoice-api:1.0.0 \
3  -t myorg/invoice-api:stable \
4  .
5
6docker images | grep invoice-api

Both tags point to the same image digest until one tag is moved by a new build. In CI, this pattern is useful for shipping immutable versions and a rolling alias.

Set Image Name in Docker Compose and CI

In Compose, you can specify the image name under the image key. If a build section is present too, Compose builds then tags the result with that name.

1services:
2  api:
3    build:
4      context: .
5      dockerfile: Dockerfile
6    image: myorg/invoice-api:dev
7    ports:
8      - "8000:8000"

Run:

docker compose up --build

In CI, image names are commonly built from repository and commit metadata. A typical pattern is tag by git commit SHA and optionally by branch.

GIT_SHA=$(git rev-parse --short HEAD)
docker build -t myorg/invoice-api:${GIT_SHA} .

Use explicit tags and avoid relying on mutable defaults in deployment manifests.

Add Labels for Traceability

Image naming solves identification, but labels provide additional audit context such as source repository or build time.

1FROM alpine:3.20
2LABEL org.opencontainers.image.source="https://example.com/myorg/invoice-api"
3LABEL org.opencontainers.image.description="Invoice API service"
4CMD ["sh", "-c", "echo service ready"]

Labels do not replace tags. They complement tags so operators can trace where an image came from.

Verify Name, Tag, and Digest

After building, inspect local images to confirm the expected name, tag, and digest.

docker image ls myorg/invoice-api
docker image inspect myorg/invoice-api:1.0.0 --format '{{.RepoTags}} {{.Id}}'

For remote registries, check pushed results before updating deployment files.

docker push myorg/invoice-api:1.0.0
docker push myorg/invoice-api:stable

Keeping verification as a release step prevents deploying the wrong tag by mistake.

Common Pitfalls

• Expecting the Dockerfile itself to set repository name. Naming is done by build tooling, not by Dockerfile instructions.
• Using only latest in production. Use immutable version tags and keep moving tags as optional aliases.
• Forgetting to tag before push. Unqualified images can end up in unexpected repos.
• Inconsistent names across local and CI environments. Define one naming convention and document it.
• Skipping post build checks. Verify tag and digest before deployment changes.

Summary

• A Dockerfile defines build steps, not final image name.
• Assign names and tags with docker build -t or Compose image configuration.
• Prefer immutable version tags for production stability.
• Use extra labels for source and build traceability.
• Always verify built tags and digests before pushing and deploying.