19.1.1.2 Build Tag Option

The build tag option, -t or --tag, supports more nuance than a single, simple name-and-version pairing, including applying multiple tags to the identical build result in one invocation, specific format and character validation rules, and the deliberate choice to omit it entirely for certain build scenarios.

Applying multiple tags in a single build

The -t flag can be repeated, applying several distinct tags to the exact same build output without needing to rebuild or separately retag afterward:

docker build -t my-api:1.4.2 -t my-api:latest -t registry.example.com/my-api:1.4.2 .

All three tags here reference the identical underlying image content, built exactly once; this is more efficient and less error-prone than building once and then issuing several separate docker tag commands afterward, since it guarantees every tag genuinely points at the exact same build result with no possibility of a separate, later retag accidentally referencing a different, subsequently rebuilt image.

Tag format and character rules

Image names and tags follow specific format constraints: repository names must be lowercase, while tags themselves can include uppercase letters, and both have restrictions on which special characters are permitted:

docker build -t My-Api:1.4.2 .

invalid reference format: repository name must be lowercase

docker build -t my-api:1.4.2 .

This case-sensitivity rule specifically applies to the repository name portion; the tag portion itself, after the colon, does permit uppercase characters, which is a subtle but occasionally confusing distinction worth knowing explicitly when a build fails with a format error that does not immediately make clear which part of the reference is actually invalid.

Length and character set restrictions on tags

Beyond case sensitivity, tags are restricted to a specific character set, letters, digits, underscores, periods, and hyphens, with a maximum length of 128 characters, which is rarely a practical constraint but worth knowing about when a build script generates a tag dynamically from some other source, like a commit message, that might contain characters outside this allowed set:

docker build -t "my-api:$(echo "$COMMIT_MSG" | tr -cd '[:alnum:]_.-')" .

Sanitizing a dynamically generated tag value explicitly, as shown here, avoids a build failing purely due to an unexpected character making its way into the tag from whatever external source originally produced it.

Including a full registry path in the tag

A tag intended for pushing to a specific, non-default registry needs the registry's hostname included directly as part of the tag itself, since omitting it causes Docker to assume Docker Hub by default:

docker build -t registry.example.com/myorg/my-api:1.4.2 .
docker push registry.example.com/myorg/my-api:1.4.2

Including this full path directly in the build's own tag, rather than tagging separately afterward with docker tag, keeps the build and push steps consistent and reduces the chance of a typo introduced in a separate, later tagging step.

Building without any tag at all

Omitting -t entirely is a valid, if less convenient, choice for a genuinely throwaway, immediate test build, producing an image identifiable only by its content-derived image ID:

docker build .

Successfully built 8a1f3c9b2e7d
docker run 8a1f3c9b2e7d

This is occasionally useful for a quick, one-off verification that a Dockerfile builds successfully at all, without needing to think of or clean up a tag name afterward, though for anything beyond an immediate, single-use test, applying at least one meaningful tag is considerably more practical for any subsequent reference to the result.

Common mistakes

• Building once and applying multiple tags through separate docker tag commands afterward, rather than using repeated -t flags in the original build to guarantee every tag references the identical result.
• Attempting to use uppercase characters in the repository name portion of a tag, triggering a format validation error.
• Not sanitizing a dynamically generated tag value derived from an external source like a commit message, risking a build failure from an unexpected, disallowed character.
• Omitting the full registry hostname from a tag intended for a non-default registry, causing Docker to assume Docker Hub instead of the actually intended destination.
• Building without any tag at all for anything beyond a genuinely immediate, throwaway test, making the result inconvenient to reference for any subsequent step.

The build tag option supports applying several tags to one build result efficiently through repeated flags, follows specific case-sensitivity and character-set validation rules worth understanding directly when a format error occurs, and can be deliberately omitted for a genuinely throwaway test build, each of which is worth knowing explicitly rather than assuming the simplest, single-tag case covers every actual scenario.