Give a Local Docker Image a Safe Registry Tag

You will add a second name to a local Docker image without rebuilding or copying its layers. This is useful for giving an image a release label, or for adding the registry and repository name it needs before a later push. Allow about five minutes if Docker is installed and the source image already exists. The commands here were checked with Docker 29.8.1 from the docker-ce-cli package on this machine.

1. Check the command and find the source image

Start by confirming the subcommand and listing local images. This is an ordinary, unprivileged command when your account can access the Docker daemon:

$ docker image tag --help
Usage:  docker image tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE

Aliases:
  docker image tag, docker tag
$ docker image ls

Choose an exact source from the REPOSITORY, TAG and IMAGE ID columns. If you leave the source tag out, Docker uses latest. That is a name convention, not a guarantee that the image is current or safe to release. A local image can be tagged by name and tag, or by its image ID.

If docker image ls fails with a daemon connection error, check the Docker service and your account's daemon access before changing anything. Do not add sudo automatically: running Docker as root can create files and images under a different user context.

2. Add a descriptive local tag

Tag a known image with a name that records the version you intend to use. Replace the example source and target with values from your own image list:

$ docker image tag example-api:build-2026-09-23 example-api:release-2026-09
$ docker image ls example-api
REPOSITORY   TAG                  IMAGE ID       CREATED        SIZE
example-api  build-2026-09-23     abcdef123456   ...            ...
example-api  release-2026-09      abcdef123456   ...            ...

The target is an alias. It points at the same image ID, so this command does not create a second copy of the image layers. The exact image ID and table formatting vary. The important check is that both tags resolve to the same ID.

If the source is identified by an image ID, the same operation is explicit and independent of the source name:

$ docker image tag abcdef123456 example-api:release-2026-09

Docker accepts a real image ID from docker image ls; the shortened value above is only an obvious placeholder. Do not paste it unless it is the ID on your host.

3. Prepare a tag for a private registry

A registry-qualified target starts with the registry host, optionally followed by a port, then the namespace and repository. This changes the name you will use for a later push, but it does not contact the registry and does not upload anything:

$ docker image tag example-api:release-2026-09 registry.example.test:5000/platform/example-api:release-2026-09
$ docker image ls registry.example.test:5000/platform/example-api
REPOSITORY                                      TAG                IMAGE ID       CREATED        SIZE
registry.example.test:5000/platform/example-api release-2026-09   abcdef123456   ...            ...

Use the real registry hostname and port supplied by its administrator. A hostname with an underscore is not valid here. Repository components use lower-case letters, digits and permitted separators. Tag names may use upper- or lower-case letters, digits, underscores, periods and hyphens, but may not start with a period or hyphen and are limited to 128 characters.

The name alone does not prove that the registry is trusted. Treat a private registry as a security boundary: use the correct hostname, confirm its TLS and authentication policy, and do not put credentials in a shell command or a tag.

4. Verify the alias before pushing

Inspect the source and target references and compare their IDs. This is read-only and does not need elevated privileges:

$ docker image inspect --format '{{.Id}} {{.RepoTags}}' example-api:release-2026-09
sha256:... [example-api:release-2026-09 registry.example.test:5000/platform/example-api:release-2026-09]
$ docker image inspect --format '{{.Id}}' registry.example.test:5000/platform/example-api:release-2026-09
sha256:...

The two ID values should match. If they do not, stop. You may have used a different source tag, or a local image may have been rebuilt since you selected it. Re-run docker image ls and choose the intended image explicitly.

Tagging is local bookkeeping. The target will not appear in a registry until a separate docker push succeeds. Check the target name before that later, state-changing operation:

$ docker image ls registry.example.test:5000/platform/example-api --format '{{.Repository}}:{{.Tag}} {{.ID}}'

5. Handle failures and undo a mistaken tag

A missing source produces an error and does not create a useful target. Test a suspected source with docker image inspect first:

$ docker image inspect example-api:does-not-exist
Error response from daemon: No such image: example-api:does-not-exist

The exact error wording depends on the daemon version. Correct the source name or tag; do not pull an image merely because a tag was mistyped. A pull can introduce a different image into the local cache.

There is no separate retag command. To remove an unwanted alias, use the target reference with docker image rm:

$ docker image rm registry.example.test:5000/platform/example-api:release-2026-09

Warning: removing a tag changes local image state. It normally removes only that reference when another tag still points to the same image, but Docker may remove unreferenced layers as well. Do not use -f as a first response. If the tag is needed, recreate it from the verified source instead:

$ docker image tag example-api:release-2026-09 registry.example.test:5000/platform/example-api:release-2026-09

If a target name already exists, decide deliberately whether it should continue pointing at its current image. Retagging it changes what that name resolves to. Use a new immutable release tag when you need an audit-friendly record; keep a moving tag such as latest only when that behaviour is intentional.